API 목록

version 1.0

  • version 1.0

엑심베이 API

엑심베이 API 엔드포인트(Endpoint)와 객체 정보, 파라미터, 요청 및 응답 예제를 살펴보세요.
엑심베이 API를 이용하면 다양한 결제 수단의 결제 연동・승인・취소・조회・인증을 구현할 수 있습니다.
API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 준비하기에서 자세히 알아보세요.

결제 준비

POST/v1/payments/ready

FGKey는 결제의 위변조 방지를 위해 가맹점과 엑심베이 사이에 요청, 응답되는 파라미터의 유효성을 검증할 때 사용하고 있습니다.
결제 준비 API를 사용해 결제창 호출에 필요한 FGKey를 생성해보세요.

결제 준비 API로 생성한 fgkey는 JavaScript SDK로 결제창을 호출할 때 반드시 필요합니다.
생성한 fgkey를 그대로 넣어서 결제창을 호출해주세요. 자세한 내용은 javascript SDK 에서 확인할 수 있습니다.

요청 파라미터

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 정보입니다.
return_url은 고객 브라우저 기반으로 동작하므로, 브라우저 강제 종료 시, 호출되지 않을 수 있습니다.

status_url string

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

* DB 작업 및 결제 프로세스 처리는 status_url에서 해야 합니다.
* 고객이 결제창을 강제 종료하면 return_url이 호출되지 않을 수 있습니다.
* 중복 호출이 가능하므로, 결제가 중복 처리되지 않게 주의가 필요합니다.

buyer object

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 객체 내 파라미터 모두를 필수로 보내야 합니다.
Note. 2 - 국내/해외 결제 따라 SDK 호출 후 받는 응답 값이 달라질 수 있습니다.

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

city string

배송지 도시 정보입니다.

country string

배송지 국가 정보입니다. 형식입니다.

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

배송지 국가 정보입니다. 형식입니다.

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 Provider를 통해 조회한 실시간 환율이 적용된 금액입니다. 카드정보가 최종 입력된 후에는 카드발급 국가의 통화로 변경될 수 있습니다.

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

call_from_app string

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

    :앱(iOS, AOS) 환경에서 호출

  2. N

    : 웹 브라우저 환경에서 호출

  3. *

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

call_from_scheme string

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

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

issuer_country string

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

ostype string

결제창이 열리는 클라이언트 환경입니다. P , M 중 하나입니다. 보내지 않으면 P가 기본으로 보내집니다.
P

: PC 환경

M

: 모바일 환경

virtualaccount_expiry_datestring

국내 가상계좌 결제의 입금만료기한을 설정할 수 있습니다. YYYYMMDDHH24로 원하는 입금만료기한을 설정할 수 있습니다.
요청
                                                
    curl --request POST 'https://api-test.eximbay.com/v1/payments/ready' \
    --header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=' \
    --header 'Content-Type: application/json' \
    --data '{
        "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"
        }
    }'
                                                
                                              
응답 파라미터

rescode string

필수
응답 코드입니다.

resmsg string

필수
응답 코드에 대한 설명입니다.

fgkey string

필수
생성된 FGKey입니다. SDK로 결제창을 호출 할 때 함께 보내줘야 합니다. 자세한 내용은 결제 준비하기를 참고하세요.
응답
                                                
    {
    	"rescode": "0000",
    	"resmsg": "Success",
    	"fgkey": "0E9BE04BA239A519E68171F26B68604ADA0A85C8350DBF5C8C0FCCF98461DB09"
    }
                                                
                                              

결제 승인

POST/v1/payments/confirm

인증 결제창으로 결제 인증 후 결제 승인 API를 호출해 결제를 마무리하세요.
요청 파라미터

transaction_type string

필수
인증 결제창으로 인증 후 결제 승인 방법을 선택할 수 있습니다. PAYMENT_PA AUTHORIZE_PA 중 하나입니다.
자세한 내용은 준비하기 를 참고하세요.
PAYMENT_PA

: 결제 승인과 함께 매입까지 자동으로 처리되는 모델입니다.

AUTHORIZE_PA

: 결제 승인만 처리되는 모델입니다. 매입 처리를 위해서 수동 매입 API를 별도로 사용해야 합니다.

mid string

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

payment object

order_id string

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

currency string

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

amount string

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

payer_auth_id string

필수
인증 결제창 PAYER_AUTH 로 결제창을 호출하고 응답으로 받은 거래 아이디입니다.

lang string

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

other_param object

param1 string

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

param2 string

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

요청
                                                    
curl --request POST 'https://api-test.eximbay.com/v1/payments/confirm' \
--header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=' \
--header 'Content-Type: application/json' \
--data '{
    "transaction_type" : "PAYMENT_PA",
    "mid" : "1849705C64",
    "payment" : {
        "order_id" : "20220902101716",
        "currency" : "USD",
        "amount" : "1",
        "payer_auth_id" : "20220902101716",
        "lang" : "EN"
    }
}'

                                                    
                                                
응답 파라미터

rescode string

필수
응답 코드입니다.

resmsg string

필수
응답 코드에 대한 설명입니다.

mid string

필수
엑심베이에서 가맹점을 구분하기 위해 발급한 고유 가맹점 ID입니다.
응답
                                                    
{
    "rescode": "0000",
    "resmsg": "Success",
    "mid": "1849705C64",
}
                                                    
                                                    
                                                

payment object

order_id string

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

currency string

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

amount string

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

email string

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

transaction_id string

필수
엑심베이에서 결제 내역을 구분하기 위해 발급한 고유 ID입니다.

auth_code string

승인번호입니다.

* 간편결제로 결제된 거래의 경우 승인번호가 존재하지 않습니다.

transaction_date string

필수
승인 일시입니다. YYYYMMDDHHMMSS 형식으로 돌아옵니다.

access_country string

고객이 결제를 진행한 국가입니다. 형식입니다.

payment_method string

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

pay_to string

청구할 가맹점명입니다.

payment_url string

일본 편의점 결제를 선택했을 때, '접수' 단계에서 고객에게 결제 방법 안내을 안내하는 url 정보입니다.

status string

결제 수단이 가상계좌 또는 일본 편의점 결제(eContext)일 때 결제처리 상태입니다.
REGISTERED

: 접수 반드시 Sale을 수신한 경우에만 주문완료 처리를 해야합니다.

Sale

: 입금 완료 시 statusurl로만 전송됩니다.

base_currency string

승인된 통화 단위입니다.

* 일반적으로 currency 파라미터와 동일 값이 돌아오며, 자국통화기준 MCP의 경우 원화(KRW) 또는 달러(USD) 로 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

base_amount string

승인된 금액입니다.

* 일반적으로 amount 파라미터와 동일 값이 돌아오며, 자국통화기준 MCP의 경우 원화(KRW) 또는 달러(USD) 로 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

base_rate string

승인통화에 적용된 환율정보입니다.

* currency대비 base_currency에 대한 환율로, 동일한 경우 1 이 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

dcc_rate string

DCC 적용 환율 정보입니다.

* base_currency대비 foreign_currency에 대한 환율로, 동일한 경우 1 이 돌아옵니다.

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

terminal_id string

VAN 단말기 아이디입니다.

card_number string

결제한 카드의 카드번호입니다.

expiry_date string

카드 유효기간입니다.

store_number string

매입사 가맹점 번호입니다.

foreign object

foreign_currency string

고객에게 청구될 통화 단위입니다.

* DCC의 경우 고객이 선택한 통화 단위가 돌아옵니다.

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

foreign_amount string

고객에게 청구할 금액입니다.

* DCC의 경우 고객이 선택한 통화 단위가 돌아옵니다.

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

foreign_rate string

고객에게 청구한 금액에 적용된 환율정보입니다.

* currency 대비 foreign_currency 에 대한 환율로 동일한 경우 1 이 들어옵니다.

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

card_info object

card_holder string

카드 명의자 이름입니다.

card_number1 string

조회한 거래에 사용된 카드의 앞 4자리 번호입니다.

card_number4 string

조회한 거래에 사용된 카드의 마지막 4자리 번호입니다.

cash_receipt object

use_flag string

현금 영수증 사용 여부를 확인할 수 있습니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

cash_receipt_type string

현금 영수증 용도입니다. 소득공제, 지출증빙 중 하나입니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

customer_information_type string

현금 영수증 발급 시 입력한 발급수단번호의 종류입니다. 휴대폰 번호, 주민등록번호, 카드번호가 될 수 있습니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

customer_information string

현금 영수증 발급 시 입력한 발급수단번호입니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

ship_to object

city string

배송지 도시 정보입니다.

country string

배송지 국가 정보입니다. 형식입니다.

first_name string

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

last_name string

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

phone_number string

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

postal_code string

배송지 우편번호입니다.

state string

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

street1 string

배송지 상세주소입니다.

dm object

decision string

DM Process의 상태입니다. 아래와 같은 상태 코드를 확인할 수 있습니다.
ACCEPT

: DM Process 위험 검토 후 거래 승인

REJECT

: DM Process 위험 검토 후 거래 실패

REVIEW

: DM Process 위험 검토 후 승인될 수 있으나, 위험 거래여부 확인이 필요한 상태

ERROR

: DM Process 실패

reject string

REJECT Rule 코드입니다. Rule 코드는 I 로 구분되며, 별도로 제공됩니다.

review string

REJECT Rule 코드입니다. Rule 코드는 I 로 구분되며, 별도로 제공됩니다.

other_param object

param1 string

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

param2 string

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

결제 검증

POST/v1/payments/verify

SDK로 결제창을 열고 받은 응답에 포함되어 있는 FGKey의 유효성 검증을 위해 필요합니다.
결제 검증 API를 사용해 결제를 마무리하세요. 아래 주의사항을 꼭 참고해주세요.

엑심베이 서버에서 가맹점 status_url로 나간 응답 파라미터는 쿼리스트링 형식입니다.
쿼리스트링으로 응답받은 파라미터를 빠짐없이 결제 검증 API 요청 파라미터로 전송해주세요.
자세한 내용은 결제 준비에서 확인할 수 있습니다.

Note. 1 - SDK로 결제창을 열 때 선택한 transaction_type과 사용한 요청 파라미터에 따라 status_url로 받은 응답 값이 달라집니다.
Note. 2 - 국내/해외 결제 따라 SDK 호출 후 받는 응답 값이 달라질 수 있습니다.

요청 파라미터

version string

필수
SDK로 호출한 결제창의 버전 정보입니다.

mid string

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

transaction_type string

필수
SDK로 결제창을 호출할 때 사용한 결제창 타입과 같습니다. 선택한 결제창 타입에 따라 엑심베이 서버에서 받은 응답 파라미터가 달라집니다.

fgkey string

필수
결제창을 호출할 때 사용한 fgkey 정보입니다.

order_id string

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

currency string

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

amount string

필수
총 결제 금액입니다.

email string

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

param1 string

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

param2 string

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

param3 string

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

rescode string

필수
응답 코드입니다.

resmsg string

필수
응답 코드에 대한 설명입니다.

transaction_id string

엑심베이에서 결제 내역을 구분하기 위해 발급한 고유 ID입니다.

auth_code string

승인번호입니다.

* 간편결제로 결제된 거래의 경우 승인번호가 존재하지 않습니다.

payer_auth_id string

인증 결제창 PAYER_AUTH 로 결제창을 호출하고 응답으로 받은 거래 아이디입니다.

transaction_date string

승인 일시입니다. YYYYMMDDHHMMSS 형식으로 돌아옵니다.

access_country string

고객이 결제를 진행한 국가입니다. 형식입니다.

payment_method string

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

payment_type string

결제수단으로 국내 간편결제를 선택했을 때 가맹점에 설정된 정보입니다.

*국내 간편결제를 사용했을 경우 필요한 파라미터입니다.

pay_to string

청구할 가맹점명입니다.

card_holder string

카드 명의자 이름입니다.

card_number1 string

거래에 사용된 카드의 앞 4자리 번호입니다.

card_number4 string

거래에 사용된 카드의 마지막 4자리 번호입니다.

installment_months string

선택한 할부 개월 수 입니다.

*국내 결제일 경우 사용할 수 있습니다.

status string

필수
결제창으로 진행한 결제의 상태입니다. 아래와 같은 상태 코드를 확인할 수 있습니다.
SALE

: 정상매출 (매출 확정)

AUTH

: 승인거래 (매출 미확정, 수동 매입시 매출 확정)

REGISTERED

: 주문등록 (매출 미확정, 입금통지시 매출 확정)

NONE

: 거래 없음

city string

배송지 도시 정보입니다.

country string

배송지 국가 정보입니다. 형식입니다.

first_name string

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

last_name string

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

phone_number string

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

postal_code string

배송지 우편번호입니다.

state string

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

street1 string

배송지 상세주소입니다.

use_flag string

현금 영수증 사용 여부를 확인할 수 있습니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

cash_receipt_type string

현금 영수증 용도입니다. 소득공제, 지출증빙 중 하나입니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

customer_information_type string

현금 영수증 발급 시 입력한 발급수단번호의 종류입니다. 휴대폰 번호, 주민등록번호, 카드번호가 될 수 있습니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

customer_information string

현금 영수증 발급 시 입력한 발급수단번호입니다.

*가상계좌, 네이버페이 포인트 결제 시 필요한 파라미터입니다.

account_number string

가상계좌 번호입니다. 결제수단으로 가상계좌를 선택했을 때 필요합니다.

bank_name string

가상계좌 은행명입니다.

depositor string

입금자 명입니다.

due_date string

가상계좌로 입금할 수 있는 입금 유효기한입니다.

Note. 1 - 고객이 결제수단으로 가상계좌 또는 일본 편의점 결제를 선택했을 때 필요한 객체입니다.
Note. 2 - 가상계좌 또는 일본 편의점 결제의 경우 아래 두 단계로 결과가 전송됩니다.
• 주문등록: returnurl, statusurl   • 입금통지: statusurl
Note. 3 - statusurl로 주문등록 결과를 받을지 여부는 선택할 수 있습니다.

payment_url string

일본 편의점 결제를 선택했을 때, '접수' 단계에서 고객에게 결제 방법 안내을 안내하는 url 정보입니다.

decision string

DM Process의 상태입니다. 아래와 같은 상태 코드를 확인할 수 있습니다.
ACCEPT

: DM Process 위험 검토 후 거래 승인

REJECT

: DM Process 위험 검토 후 거래 실패

REVIEW

: DM Process 위험 검토 후 승인될 수 있으나, 위험 거래여부 확인이 필요한 상태

ERROR

: DM Process 실패

reject string

REJECT Rule 코드입니다. Rule 코드는 I 로 구분되며, 별도로 제공됩니다.

review string

REJECT Rule 코드입니다. Rule 코드는 I 로 구분되며, 별도로 제공됩니다.

base_currency string

승인된 통화 단위입니다.

* 일반적으로 currency 파라미터와 동일 값이 돌아오며, 자국통화기준 MCP의 경우 원화(KRW) 또는 달러(USD) 로 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

base_amount string

승인된 금액입니다.

* 일반적으로 amount 파라미터와 동일 값이 돌아오며, 자국통화기준 MCP의 경우 원화(KRW) 또는 달러(USD) 로 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

base_rate string

승인통화에 적용된 환율정보입니다.

currency 대비 base_currency 에 대한 환율로, 동일한 경우 1 이 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

foreign_currency string

고객에게 청구될 통화 단위입니다.

* DCC의 경우 고객이 선택한 통화 단위가 돌아옵니다.

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

foreign_amount string

고객에게 청구할 금액입니다.

* DCC의 경우 고객이 선택한 통화에 맞는 금액이 돌아옵니다.

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

foreign_rate string

고객에게 청구한 금액에 적용된 환율정보입니다.

*currency 대비 foreign_currency 에 대한 환율로 동일한 경우 1 이 돌아옵니다.

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

dcc_rate string

DCC 적용 환율 정보입니다.

base_currency 대비 foreign_currency 에 대한 환율로, 동일한 경우 1 이 돌아옵니다.

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

terminal_id string

VAN 단말기 아이디입니다.

card_number string

결제한 카드의 카드번호입니다.

expiry_date string

카드 유효기간입니다.

store_number string

매입사 가맹점 번호입니다.

cavv string

인증결과에 대한 cavv 정보입니다.

xid string

인증결과에 대한 xid입니다.

eci string

인증결과에 대한 eci 정보입니다.
요청
                                                    
curl --request POST 'https://api-test.eximbay.com/v1/payments/verify' \
--header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=' \
--header 'Content-Type: application/json' \
--data '{
    "data" : "currency=USD&card_number1=4111&transaction_date=20220927152250&card_number4=1111&mid=1849705C64&amount=100&access_country=KR&order_id=20220927152140&payment_method=P101&email=test@eximbay.com&ver=230&transaction_id=1849705C6420220927000016&param3=TEST&resmsg=Success.&card_holder=TESTP&rescode=0000&auth_code=309812&fgkey=2AE38D785E05E6AF57977328908C7CD84A273B3FE6C042D537A800B0CBC783EA&transaction_type=PAYMENT&pay_to=EXIMBAY.COM"
	    }'
                                                    
                                                
응답 파라미터

rescode string

필수
응답 코드입니다.

resmsg string

필수
응답 코드에 대한 설명입니다.
응답
                                                    
    {
        "rescode": "0000",
        "resmsg": "Success",
    }
                                                    
                                                  

결제 조회

POST/v1/payments/retrieve

승인 또는 취소된 결제를 조회할 수 있습니다.
요청 파라미터

mid string

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

key_field string

필수
결제 조회 방법을 선택할 수 있습니다. order_id , transaction_id 중 하나입니다. 보내지 않으면 transaction_id 가 기본으로 보내집니다.
order_id

: 승인 또는 환불된 최종 거래를 조회할 수 있습니다.

transaction_id

: 지정된 거래를 조회할 때 사용합니다.

payment object

order_id string

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

currency string

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

amount string

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

lang string

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

transaction_id string

엑심베이에서 결제 내역을 구분하기 위해 발급한 고유 ID입니다.

other_param object

param1 string

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

param2 string

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

요청
                                                    
curl --request POST 'https://api-test.eximbay.com/v1/payments/retrieve' \
--header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=' \
--header 'Content-Type: application/json' \
--data '{
    "mid" : "1849705C64",
    "key_field" : "order_id", 
    "payment" : {
        "order_id" : "20220902101716",
        "currency" : "USD",
        "amount" : "1",
        "transaction_id" : "20220902101716",
        "lang" : "EN"
    }
}'
                                                    
                                                
응답 파라미터

rescode string

필수
응답 코드입니다.

resmsg string

필수
응답 코드에 대한 설명입니다.

mid string

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

payment object

status string

필수
조회한 결제의 상태입니다. 아래와 같은 상태 코드를 확인할 수 있습니다.
SALE

: 정상매출 (매출 확정)

AUTH

: 승인거래 (매출 미확정, 수동 매입시 매출 확정)

REGISTERED

: 주문등록 (매출 미확정, 입금통지시 매출 확정)

NONE

: 거래 없음

order_id string

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

currency string

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

amount string

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

transaction_id string

필수
엑심베이에서 결제 내역을 구분하기 위해 발급한 고유 ID입니다.

auth_code string

승인번호입니다.

* 간편결제로 결제된 거래의 경우 승인번호가 존재하지 않습니다.

transaction_date string

필수
조회한 거래의 승인 일시입니다. YYYYMMDDHHMMSS 형식으로 돌아옵니다.

balance string

취소 가능 금액입니다. (승인 금액 - 환불 금액)

payment_method string

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

card_info object

card_number1 string

조회한 거래에 사용된 카드의 앞 4자리 번호입니다.

card_number4 string

조회한 거래에 사용된 카드의 마지막 4자리 번호입니다.

other_param object

param1 string

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

param2 string

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

응답
                                                    
    {
        "rescode": "0000",
        "resmsg": "Success.",
        "mid": "1849705C64",
        "payment": {
            "order_id": "20220902101716",
            "currency": "USD",
            "amount": "1",
            "transaction_id": "1849705C6420220902000010",
            "status": "AUTH",
            "auth_code": "485760",
            "transaction_date": "20220902101749",
            "balance": "1.00"
        },
        "card_info": {
            "cardno1": "4111",
            "cardno4": "1111"
        }
    }
                                                    
                                                  

결제 취소

POST/v1/payments/{transaction_id}/cancel

승인된 결제를 transaction_id 로 취소합니다.
요청 파라미터

mid string

필수

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

refund object

refund_type string

필수
결제 취소에 대한 타입정보입니다. FP 중 하나입니다.
F

: 전체 취소

P

: 부분 취소

refund_amount string

필수

요청한 취소 금액입니다. 원승인 거래 금액을 초과해 요청할 수 없습니다. refund_typeF 일 때 금액을 보내지 않으면 원승인 거래 전체 금액이 취소됩니다.

refund_id string

필수

취소하려는 거래를 구분하기 위해 가맹점에서 생성하는 고유한 취소 번호입니다. 취소 번호는 유일한 값을 가져야 합니다.

reason string

필수

결제를 취소한 이유입니다.

payment object

order_id string

필수

취소하려는 거래의 주문번호(odrer_id)입니다. 동일한 주문번호를 넣어야 취소가 정상적으로 처리됩니다.

currency string

필수

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

amount string

필수

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

balance string

필수

취소 가능 금액입니다. (승인 금액 - 환불 금액)

lang string

필수

결제창에 지원되는 언어 코드입니다. 를 참고하세요.

other_param object

param1 string

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

param2 string

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

refund_account object

user_name string

고객이 입력할 환불계좌 정보의 예금주명입니다.

bank_code string

고객이 입력할 환불계좌의 은행코드입니다.

account_number string

고객이 입력할 환불계좌의 계좌번호입니다.

tax object*가상계좌 또는 네이버페이로 결제한 거래를 취소할 때 필요한 파라미터입니다.

receipt_status string

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

amount_tax_free string

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

amount_taxable string

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

amount_vat string

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

amount_service_fee string

전체 결제 금액 중 봉사료입니다.
요청
                                                    
curl --request POST 'https://api-test.eximbay.com/v1/payments/{transaction_id}/cancel' \
--header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=' \
--header 'Content-Type: application/json' \
--data '{
    "mid" : "1849705C64",
    "refund" : {
        "refund_type" : "F",
        "refund_amount" : "1",
        "refund_id" : "1849705C64",
        "reason" : "단순변심"
    },
    "payment" : {
        "order_id" : "20220829170258",
        "currency" : "USD",
        "amount" : "1",
        "balance" : "1",
        "lang" : "EN"
    }
}'
                                                    
                                                    
                                                
응답 파라미터

rescode string

필수

응답 코드입니다.

resmsg string

필수

응답 코드에 대한 설명입니다.

mid string

필수

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

refund object

refund_amount string

필수

요청한 취소 금액입니다. 원승인 거래 금액을 초과해 요청할 수 없습니다. refund_typeF 일 때 금액을 보내지 않으면 원승인 거래 전체 금액이 취소됩니다.

refund_id string

필수

취소하려는 거래를 구분하기 위해 가맹점에서 생성하는 고유한 취소 번호입니다. 취소 번호는 유일한 값을 가져야 합니다.

refund_date string

필수

결제가 취소된 일시입니다. YYYYMMDDHHMMSS 형식으로 돌아옵니다.

refund_transaction_id string

필수

엑심베이에서 취소된 거래를 구분하기 위해 발급한 고유한 아이디입니다.

payment object

order_id string

필수

취소하려는 거래의 주문번호(odrer_id)입니다. 동일한 주문번호를 넣어야 취소가 정상적으로 처리됩니다.

currency string

필수

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

amount string

필수

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

transaction_id string

필수

엑심베이에서 결제 내역을 구분하기 위해 발급한 고유 ID입니다.

balance string

필수

취소 가능 금액입니다. (승인 금액 - 환불 금액)

auth_code string

승인번호입니다.

* 간편결제로 결제된 거래의 경우 승인번호가 존재하지 않습니다.

base_amount string

승인된 금액입니다.

* 일반적으로 amount 파라미터와 동일 값이 돌아오며, 자국통화기준 MCP의 경우 원화(KRW) 또는 달러(USD) 로 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

base_rate string

승인통화에 적용된 환율정보입니다.

currency 대비 base_currency 에 대한 환율로, 동일한 경우 1 이 돌아옵니다.

* 직가맹점은 매입데이터로 사용할 수 있습니다.

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

dcc_rate string

DCC 적용 환율 정보입니다.

base_currency 대비 foreign_currency 에 대한 환율로, 동일한 경우 1 이 돌아옵니다.

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

foreign objcet

foreign_currency string

고객에게 청구될 통화 단위입니다.

* DCC의 경우 고객이 선택한 통화 단위가 돌아옵니다.

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

foreign_amount string

고객에게 청구할 금액입니다.

* DCC의 경우 고객이 선택한 통화에 맞는 금액이 돌아옵니다.

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

foreign_rate string

고객에게 청구한 금액에 적용된 환율정보입니다.

* currency 대비 foreign_currency 에 대한 환율로 동일한 경우 1 이 돌아옵니다.

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

other_param object

param1 string

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

param2 string

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

응답
                                                
    {
        "rescode": "0000",
        "resmsg": "Success.",
        "mid": "1849705C64",
        "refund": {
            "refund_amount": "1.00",
            "refund_id": "1849705C64",
            "refund_date": "20220922113927",
            "refund_transaction_id": "1849705C6420220922000014"
        },
        "payment": {
            "order_id": "20220922113330",
            "currency": "USD",
            "amount": "1.00",
            "transaction_id": "1849705C6420220922000013",
            "balance": "0.00",
            "base_amount": "1.00",
            "base_rate": "1.000000",
            "dcc_rate": "1.000000",
    		"payment_method" : "P101"
        },
        "foreign": {
            "foregin_currency": "USD",
            "foregin_amount": "1.00",
            "foregin_rate": "0"
        }
    }
                                                    
                                                  

수동 매입

POST/v1/payments/{transaction_id}/capture

정산받고 싶은 결제를 transaction_id 로 엑심베이에 요청하세요.
요청 파라미터

mid string

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

payment object

order_id string

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

currency string

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

amount string

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

lang string

필수
결제창에 지원되는 언어 코드입니다. 를 참고하세요.

other_param object

param1 string

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

param2 string

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

요청
                                                    
curl --request POST 'https://api-test.eximbay.com/v1/payments/{transaction_id}/capture' \
--header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=' \
--header 'Content-Type: application/json' \
--data '{
    "mid" : "1849705C64",
    "payment" : {
        "order_id" : "20220902101716",
        "currency" : "USD",
        "amount" : "1",
        "lang" : "EN"
    }
}'
                                                    
                                                
응답 파라미터

rescode string

필수
응답 코드입니다.

resmsg string

필수
응답 코드에 대한 설명입니다.

mid string

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

payment object

order_id string

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

transaction_id string

필수
엑심베이에서 결제 내역을 구분하기 위해 발급한 고유 ID입니다.

currency string

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

amount string

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

lang string

필수
결제창에 지원되는 언어 코드입니다. 를 참고하세요.

captured_date string

필수
수동매입 요청에 대한 응답시간입니다. YYYYMMDDHHMMSS 형식으로 돌아옵니다.

partially_cancelable string

부분취소 가능 여부입니다. Y , N 중 하나입니다. 보내지 않으면 N 이 기본으로 보내집니다.
Y

: 부분취소가 가능합니다.

N

: 부분취소가 불가능합니다.

other_param object

param1 string

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

param2 string

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

응답
                                                    
    {
        "rescode": "0000",
        "resmsg": "Success.",
        "mid": "1849705C64",
        "payment": {
            "order_id": "20220922114007",
            "currency": "USD",
            "amount": "1",
            "transaction_id": "1849705C6420220922000016",
            "captured_date": "20220922114212",
            "allowed_pvoid": "Y"
        }
    }