EXIMBAY 개발자센터

JavaScript SDK

엑심베이 JavaScript SDK로 웹사에트에 결제창을 연동하세요.
SDK 사용을 위한 설치 방법, 메서드 사용 방법, 파라미터 정보, 결제 실패 및 에러 처리 방법을 확인할 수 있습니다.

엑심베이는 가맹점이 용도에 맞게 사용할 수 있는 다양한 종류의 결제창을 제공하고 있습니다.
SDK로 결제창을 호출할 때 아래 transaction_type으로 원하는 결제창을 호출하세요.

결제창을 호출할 때 transaction_type에 따라 호출된 결제창의 기능이 달라집니다.
PAYMENT: 결제창이 호출되면 인증, 승인 그리고 매입까지 자동으로 처리되는 통합 결제창이 열립니다.
PAYER_AUTH: 결제창이 호출되면 인증만 처리되며, 이후 승인과 매입을 처리하기 위한 API를 추가로 호출해야 하는 인증 결제창입니다.
AUTHORIZE: 결제창이 호출되면 인증과 승인만 처리되는 승인 결제창입니다. 이후 매입을 위해 수동 매입 API를 호출이 필요합니다.

수동 매입 API는 추가 계약 후 사용할 수 있습니다. 관련해서는 문의하기를 이용해주세요.

SDK 설치하기

결제창을 연동할 HTML 페이지에 엑심베이 JavaScript SDK 라이브러리를 추가해야 합니다.

                    
<!-- jQuery -->
<script type="text/javascript" src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<!-- SDK  -->
<script type="text/javascript" src="https://api-test.eximbay.com/v1/javascriptSDK.js"></script>

라이브러리 설치가 완료되면 EXIMBAY.request_pay() 메서드를 호출해 결제창을 띄울 수 있습니다.

결제창 띄우기

결제창을 띄우기 전에 결제 위변조 확인을 위한 fgkey를 먼저 생성해야 합니다. fgkey는 결제 준비 API로 간편하게 생성할 수 있습니다.
자세한 내용은 결제 준비를 참고하세요.

결제 준비 API로 fgkey를 생성했다면, 응답 값으로 받은 fgkey를 그대로 사용해 SDK를 호출하세요.

SDK를 사용해 결제창을 띄울 때는 반드시 앞서 호출한 결제 준비 API로 보낸 요청 파라미터와 일치하는 값을 보내야 합니다.
파라미터 값이 달라지면 fgkey가 달라지기 때문에 결제가 실패합니다.

                  
<button type="button" onclick="payment();">결제 창 연동</button>
	.
	.
	.
<script type="text/javascript">
      function payment() {
          // 결제 창 연동 sdk
          EXIMBAY.request_pay({
							// Fgkey that created by Payment Ready API
              "fgkey" : "0E9BE04BA239A519E68171F26B68604ADA0A85C8350DBF5C8C0FCCF98461DB09",
              "payment" : {
                  "transaction_type" : "PAYMENT",
                  "order_id" : "20220819105102",
                  "currency" : "USD",
                  "amount" : "1",
                  "lang" : "EN"
              },
              "merchant" : {
                  "mid" : "1849705C64"
              },
              "buyer" : {
                  "name" : "eximbay",
                  "email" : "test@eximbay.com"
              },
              "url" : {
                  "return_url" : "eximbay.com",
                  "status_url" : "eximbay.com"
              }
          });
      }
</script>

SDK 파라미터

결제창을 띄우기 위해 필요한 상세 파라미터 정보를 확인할 수 있습니다.

fgkey string

필수

FGKey입니다. 결제 준비 API에서 받은 fgkey를 그대로 보내야 합니다. 자세한 내용은 결제 준비를 참고하세요.

payment object

transaction_type string

필수

연동하려는 결제창 타입 구분을 위해 필요합니다. PAYMENT PAYER_AUTH AUTHORIZE 중 하나입니다. 자세한 내용은 준비하기를 참고하세요.

PAYMENT
: 결제창이 호출되고 인증, 결제 승인 그리고 매입까지 자동으로 처리되는 모델입니다.
PAYER_AUTH
: 결제창이 호출되면 인증만 처리되며, 승인과 매입이 자동으로 처리되는 API 또는, 승인만 이루어지는 API 호출이 독립적으로 필요한 모델입니다.
AUTHORIZE
: 결제창이 호출되면 인증과 승인까지 자동으로 처리되며, 매입(정산)은 가맹점에서 수동 매입 API를 호출해 요청해야 합니다

* 수동 매입 API를 사용하려면 별도의 계약이 필요합니다.

order_id string

필수

가맹점에서 주문 건을 구분하기 위해 발급한 유일한 값입니다. 실패한 주문에 같은 값을 사용할 수 없습니다.

currency string

필수

결제에 사용한 통화 단위입니다 . 자세한 내용은 통화 코드를 참고하세요.

amount string

필수

총 결제 금액입니다. , 는 사용할 수 없으며, 0보다 큰 숫자만 보낼 수 있습니다.

lang string

필수

결제창에서 사용할 수 있는 언어 코드입니다. 결제창 지원 언어 코드를 참고하세요.

payment_method string

결제수단 코드입니다. 결제수단 코드를 참고하세요. 결제 수단이 지정된 경우, 해당 결제 수단 페이지로 바로 이동합니다.

multi_payment_method string

여러 결제 수단을 지정할 때 보내야 합니다. 구분자 - 를 사용해 지정할 수 있습니다. (e.g. P000-P185-P186)

*해외 결제 연동시 사용할 수 있습니다.

merchant object

mid string

필수

엑심베이에서 가맹점을 구분하기 위해 발급한 고유 가맹점 ID입니다.

shop string

상점명입니다. 가맹점명과 다를 경우 사용해주세요.

partner_code string

파트너 코드입니다.

url object

return_url string

필수

구매자가 결제 결과를 확인화면에서 결제창을 종료할 경우 이동하는 가맹점 페이지의 url 정보입니다.
returnurl은 고객 브라우저 기반으로 동작하므로, 브라우저 강제 종료 시, 호출되지 않을 수 있습니다.

status_url string

필수

결제 처리가 끝나면 Backend로 호출되는 가맹점 페이지로 returnurl와 파라미터가 동일합니다.
브라우저에서 호출되지 않으므로, 스크립트, 쿠키, 세션은 사용할 수 없습니다.

* DB작업 및 결제 프로세스 처리는 statusurl에서 해야 합니다. 고객이 결제창을 강제 종료하면 returnurl이 호출되지 않을 수 있습니다.

* 중복 호출이 가능하므로, 결제가 중복 처리되지 않게 주의가 필요합니다.

buyerobject

name string

필수

구매자명입니다

phone_number string

구매자 전화번호입니다.

email string

필수

구매자 이메일 주소입니다. (결제완료 메일 발송을 위해 필요합니다.)

tax object*국내결제 시 필요한 파라미터 정보입니다.

receipt_status string

현금영수증 발급 여부를 Y, N 중 선택할 수 있습니다. 실시간 계좌이체를 사용하는 경우 현금영수증 발급을 위해서 반드시 Y로 요청해야 현금영수증 발급이 가능합니다.

amount_tax_free string

전체 결제 금액 중 면세 금액입니다.

amount_taxable string

전체 결제 금액 중 과세 금액입니다.

amount_vat string

전체 결제 금액 중 부가세 금액입니다.

amount_service_fee string

전체 결제 금액 중 봉사료입니다.

Note. 1 - 네이버페이 포인트로 결제를 진행하는 경우 tax 객체 내 파라미터 모두를 필수로 보내야 합니다.

other_param object

param1 string

가맹점이 필요한 경우 사용할 수 있는 예비 파라미터입니다.

param2 string

가맹점이 필요한 경우 사용할 수 있는 예비 파라미터입니다.

product array 배열의 길이는 최대 3입니다.

name string

필수

주문한 상품의 상품명입니다.

quantity string

필수

주문한 상품의 수량입니다.

unit_price string

필수

주문한 상품의 상품별 단가입니다.

link string

필수

주문한 상품의 판매 링크입니다. 오픈마켓에서 발생한 주문의 경우 필수로 보내야 합니다.

surcharge array 배열의 길이는 최대 3입니다.

name string

추가 금액의 항목명입니다. (e.g. 쿠폰할인, 배송비)

quantity string

추가된 항목의 수량입니다. 0보다 큰 숫자를 보내야 합니다.

unit_price string

추가된 항목의 단가입니다. , 는 포함할 수 없으며, 음수로 보낼 수 있습니다. (e.g. -100.50, 9.15)

ship_to object

city string

배송지 도시 정보입니다.

country string

배송지 국가 정보입니다. ISO 3166 두 자리 국가 코드 형식입니다.

first_name string

배송받는 사람의 이름입니다.

last_name string

배송받는 사람의 성입니다.

phone_number string

배송받는 사람의 연락처입니다. 국가번호가 포함될 수 있습니다.

postal_code string

배송지 우편번호입니다.

state string

배송지 주 정보입니다. 배송지가 미국(US) 또는 캐나다(CA)인 경우 사용할 수 있습니다. 지역 코드를 참고하세요.

street1 string

배송지 상세주소입니다.

bill_to object

city string

청구지 도시 정보입니다.

country string

배송지 국가 정보입니다. ISO 3166 두 자리 국가 코드 형식입니다.

first_name string

청구 카드 명의자 이름입니다.

last_name string

청구 카드 명의자 성입니다.

phone_number string

청구 카드 명의자 연락처입니다. 국가번호가 포함될 수 있습니다.

postal_code string

청구지 우편번호입니다.

state string

청구지 주 정보입니다. 청구지가 미국(US) 또는 캐나다(CA)인 경우 사용할 수 있습니다. 지역 코드를 참고하세요.

street1 string

청구지 상세주소입니다.

settings object

display_type string

브라우저에서 결제창이 열리는 방법을 정할 수 있습니다. P,R중 하나입니다. 보내지 않으면 P가 기본으로 보내집니다.

P
: 팝업 형태로 결제창 생성
R
: 가맹점 화면에서 결제창 화면으로 이동

autoclose string

결제가 완료됐을 때 브라우저에서 결제창이 닫히는 방식을 정할 수 있습니다.

Y,N 중 하나입니다. 보내지 않으면 N이 기본으로 보내집니다.
Y
: 가맹점 화면으로 이동
N
: 결제창의 완료 화면으로 이동(기본)

site_foreign_currency string

결제창에 고객이 가맹점 사이트에서 설정한 통화로 금액을 보여주기 위해 필요합니다.

*
payment_method 파라미터를 사용한 경우 P000(신용카드)만 보낼 수 있습니다.
*
가맹점에서 DCC를 사용할 경우, DCC 지원통화만 결제창에서 보여줄 수 있습니다. DCC 지원 통화는 DCC 통화 코드에서 확인할 수 있습니다.
*
금액은 엑심베이 DCC Provider를 통해 조회한 실시간 환율이 적용된 금액입니다.
카드정보가 최종 입력된 후에는 카드발급 국가의 통화로 변경될 수 있습니다.
*
해외 결제 연동시 사용할 수 있습니다.

call_from_app string

클라이언트 환경 구분을 위해 사용됩니다. Y , N 중 하나입니다. 보내지 않으면 N이 기본으로 보내집니다.

Y
:앱(iOS, AOS) 환경에서 호출
N
: 웹 브라우저 환경에서 호출
*
앱 환경에서 결제창을 호출할 경우 웹뷰에서 외부 앱 열기의 연동 방법을 확인해주세요.

call_from_scheme string

외부 앱에서 가맹점 앱으로 돌아오기 위해 필요한 앱 스킴(App URL Scheme)입니다.

*
앱 환경에서 결제창을 호출할 경우 웹뷰에서 외부 앱 열기의 연동 방법을 확인해주세요.

issuer_country string

해외 결제를 사용하는 가맹점에서 국내 결제를 사용하고 싶을 때 필요한 파라미터입니다. 파라미터에 KR을 추가하면
국내 결제창이 열립니다.

ostype string

결제창이 열리는 클라이언트 환경 정보입니다. P , M 중 하나이며 P가 기본 값입니다.

P
: PC 환경 (기본값)
M
: 모바일 환경

virtualaccount_expiry_datestring

국내 가상계좌 결제의 입금만료기한을 설정할 수 있습니다. YYYYMMDDHH24로 원하는 입금만료기한을 설정할 수 있습니다.

SDK 에러코드

SDK를 호출할 때 나타난 에러코드는 에러코드에서 확인하세요.