Consolidated Payment

Consolidated Payment includes Authentication, Authorization and Capture in one transaction. For Integrated Payment, put PAYMENT in transaction_type and
open the SDK. If you want to know about other types of payment page, refer to JavaScript SDK.

통합 결제창 연동

1. Install SDK Library

Install the Eximbay library on the HTML page where you want to integrate the payment window.

                    
<!-- 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>
                    
                  

After you have installed a Eximbay SDK, you can request the EXIMBAY.request_pay() method for open the payment SDK.

For more information, refer to JavaScript SDK

2. Create FGKey

Before calling SDK, merchant need fgkey to request Payment Ready API to check parameter forgery and alteration.

For more information, refer to Preparing fgkey.

Request
                      
  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"
        	 }
  	 }'
                      
                    
                      
  RestTemplate restTemplate = new RestTemplate();
  
  HttpHeaders headers = new HttpHeaders();
  headers.add("Content-Type", "application/json");
  headers.add("Authorization", "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=");
  
  URI url = URI.create("https://api-test.eximbay.com/v1/payments/ready");
  
  String body = "{\n" +
  			        "\"payment\" : {\n" +
  			        "\"transaction_type\" : \"PAYMENT\",\n" +
  			        "\"order_id\" : \"20220819105102\",\n" +
  			        "\"currency\" : \"USD\",\n" +
  			        "\"amount\" : \"1\",\n" +
  			        "\"lang\" : \"EN\"\n" +
  			        "},\n" +
  			        "\"merchant\" : {\n" +
  			        "\"mid\" : \"1849705C64\"\n" +
  			        "},\n" +
  			        "\"buyer\" : {\n" +
  			        "\"name\" : \"eximbay\",\n" +
  			        "\"email\" : \"test@eximbay.com\"\n" +
  			        "},\n" +
  			        "\"url\" : {\n" +
  			        "\"return_url\" : \"eximbay.com\",\n" +
  			        "\"status_url\" : \"eximbay.com\"\n" +
  			        " }\n" +
  			        "}";
  
  HttpEntity<String> entity = new HttpEntity<>(body, headers);
  ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);
  
  System.out.println(response.getBody());
                      
                    
                      
  <?php
  $url = 'https://api-test.eximbay.com/v1/payments/ready';
  $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"
    }
  }';
  
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo='));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_POST, 1);
  
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  $response  = curl_exec($ch);
  
  echo $response;
  curl_close($ch);
  ?>
                      
                    
                      
  import requests
  import json
  
  url = "https://api-test.eximbay.com/v1/payments/ready"
  headers = {
  "Authorization": "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=",
  "Content-Type": "application/json"
  }
  
  request = {
  "payment": {
    "transaction_type": "PAYMENT",
    "order_id": "20220819105102",
    "currnecy": "USD",
    "amount": "1",
    "lang": "EN"
  	 },
  "merchant": {
    "mid": "1849705C64",
 	  },
  "buyer": {
    "name": "eximbay",
    "email": "test@eximbay.com"
  	 },
  "url": {
    "return_url": "eximbay.com",
    "status_url": "eximbay.com"
  	 }
  }
  response = requests.post(url, headers=headers, data=json.dumps(request))
  
  print(response.text)
                      
                    
                      
  var request = require('request');
  var options = {
  'method': 'POST',
  'url': 'https://api-test.eximbay.com/v1/payments/ready',
  'headers': {
    'Authorization': 'Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "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"
    }
  })
  
  };
  request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
  });
                      
                    
                        
  string uri = "https://api-test.eximbay.com/v1/payments/ready";
  string body = "{\n" +
  			        "\"payment\" : {\n" +
  			        "\"transaction_type\" : \"PAYMENT\",\n" +
  			        "\"order_id\" : \"20220819105102\",\n" +
  			        "\"currency\" : \"USD\",\n" +
  			        "\"amount\" : \"1\",\n" +
  			        "\"lang\" : \"EN\"\n" +
  			        "},\n" +
  			        "\"merchant\" : {\n" +
  			        "\"mid\" : \"1849705C64\"\n" +
  			        "},\n" +
  			        "\"buyer\" : {\n" +
  			        "\"name\" : \"eximbay\",\n" +
  			        "\"email\" : \"test@eximbay.com\"\n" +
  			        "},\n" +
  			        "\"url\" : {\n" +
  			        "\"return_url\" : \"eximbay.com\",\n" +
  			        "\"status_url\" : \"eximbay.com\"\n" +
  			        " }\n" +
  			        "}";
  
  WebClient webClient = new WebClient();
  webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
  webClient.Headers[HttpRequestHeader.Authorization] = "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=";
  webClient.Encoding = UTF8Encoding.UTF8;
  string responseJSON = webClient.UploadString(uri, body);
  
  Console.Write(responseJSON);
                        
                    
                        
  val restTemplate =  RestTemplate()
  val headers = HttpHeaders()
  headers.add("Content-Type", "application/json")
  headers.add("Authorization", "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=")
  
  var url = URI.create("https://api-test.eximbay.com/v1/payments/ready")
  
  val body = "{\n" +
  		        "\"payment\" : {\n" +
  		        "\"transaction_type\" : \"PAYMENT\",\n" +
  		        "\"order_id\" : \"20220819105102\",\n" +
  		        "\"currency\" : \"USD\",\n" +
  		        "\"amount\" : \"1\",\n" +
  		        "\"lang\" : \"EN\"\n" +
  		        "},\n" +
  		        "\"merchant\" : {\n" +
  		        "\"mid\" : \"1849705C64\"\n" +
  		        "},\n" +
  		        "\"buyer\" : {\n" +
  		        "\"name\" : \"eximbay\",\n" +
  		        "\"email\" : \"test@eximbay.com\"\n" +
  		        "},\n" +
  		        "\"url\" : {\n" +
  		        "\"return_url\" : \"eximbay.com\",\n" +
  		        "\"status_url\" : \"eximbay.com\"\n" +
  		        " }\n" +
  		        "}"
  
  var entity = HttpEntity<String>(body, headers)
  var response = restTemplate.exchange(url, HttpMethod.POST, entity, String::class.java)
  
  println(response.body)
                        
                    

You can get a fgkey in the response as shown below.

                    
{
  	"rescode": "0000",
  	"resmsg": "Success",
  	"fgkey": "0E9BE04BA239A519E68171F26B68604ADA0A85C8350DBF5C8C0FCCF98461DB09"
  }
                    
                  

3. Request the Payment page

After create fgkey with the Payment Ready API, you can open the payment page successfully. To call the Consolidated Payment, put PAYMENT in transaction_type.

When open the payment window using the SDK, you must send a value that matches the request parameter sent to the FGKey generation API called earlier. The payment fails because the generated fgkey with different parameter values is different.

                  
  <script type="text/javascript" src="https://api-test.eximbay.com/v1/javascriptSDK.js"></script>
                  
                

After you have installed the Eximbay SDK, you can reqeust the request_pay method with the Eximbay object.

                  
  <button type="button" onclick="payment();">결제 창 연동</button>
  	.
  	.
  	.
  <script type="text/javascript">
        function payment() {
            EXIMBAY.request_pay({
                "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 parameters

You can check the detailed parameter information required to open the payment page.

fgkey string

Require
Please put this FGKey, when you use SDK for payments. You can refer to Preparing FGKey.

payment object

transaction_type string

Require
It is necessary to classify the SDK Type for the online payment. For the details, please refer to Preparing Payments.
  1. PAYMENT

    : This type includes Authentication, Authorization and Capture in one transaction.

* Capture API is available after a seperate contract. Please contact us.

order_id string

Require

This is the unique order ID issued by Merchant to identify accept of canceled transactions. (e.g. orderid)

currency string

Require

The type of currency in currency codes.

amount string

Require

Total payment amount. , is not allowed, only numbers greater than zero can be sent.

lang string

Require

The type of language shown in the payment SDK. Refer to the Supported Languages.

payment_method string

The type of payment method. Refer to payment method codes.
This parameter is used when you want to call a specific payment method.

multi_payment_method string

Must be sent when specifying multiple payment methods. Use separator -. (e.g. P000-P185-P186) 

merchant object

mid string

Require

This is the unique merchant ID issued by Eximbay to identify merchants.

shop string

Shop Name. Required when Shop name is different from Merchant name.

partner_code string

Partner Codes.

url object

return_url string

Require

Merchant page that is called when the user exits the payment screen on the payment result confirmation screen.
Since returnurl operates based on the customer's browser, it may not be cal led if the browser is forcibly closed.

status_url string

Require
After payment is completed, it is the merchant page called from Backend, and the return url and parameter are the same.
Since it is not called from the browser, scripts, cookies, and sessions cannot be used.

* DB operation and payment process must be handled by statusurl, and returnurl may not be called
depending on the payment method or when the customer forcibly closes the payment screen.

* Since statusurl can be called in duplicate, please make sure that your order is not processed in duplicate.

buyer object

name string

Require

Name of buyer.

phone_number string

Contact number of buyer.

email string

Require

Email address of buyer. This email is necessary for sending payment confirmation email.

tax object* This Parameters are for domestic payments.

amount_tax_free string

Tax-free amount out of the total payment amount.

amount_taxable string

Taxable amount out of the total payment amount.

amount_vat string

Require

VAT out of the total payment amount.

amount_service_fee string

Require

Service-fee out of the total payment amount.

Note. 1 - You must send all parameters in the tax object when you proceed with payment with Naver Pay points.

other_param object

param1 string

Preliminary parameters that merchants can use if needed.

param2 string

Preliminary parameters that merchants can use if needed.

product array* Array length is up to 3.

name string

Require

The product name of the ordered product.

quantity string

Require

The quantity of the ordered product.

unit_price string

Require

The unit price of the ordered product.

link string

Require

Link of the ordered product. For orders placed on the open market, it is mandatory to send it.

surcharge array* Array length is up to 3.

name string

The name of the surcharge. (e.g. coupon,, shipping fee)

quantity string

The quantity of the surcharge. Quantity can only be positive.

unit_price string

Discount unit price of the surcharge. , cannot include and discount unit price can be positive, negative. (e.g. -100.50, 9.15)

ship_to object

city string

The name of the shipping city.

country string

The type of country in ISO 3166 format.

first_name string

The first name of the recipient of the shipment.

last_name string

The last name of the recipient of the shipment.

phone_number string

The phone number of the recipient of the shipment.

postal_code string

The postal code of the shipping address.

state string

State or province of the shipping address. Required only when the shipping country is US or CA. (e.g. MA, NY, CA)
Refer to State, Province and Territory Codes for the United States and Canada.

street1 string

The street of the shipping address. (e.g. 123 Main street, 56 Le Loi street)

bill_to object

city string

Information of billing city.

country string

Information on billing country. ISO 3166 Two-digit country code format. Refer to Country Codes.

first_name string

The First Name of the billing card holder.

last_name string

The Last Name of the billing card holder.

phone_number string

The phone number of the billing card holder.

postal_code string

The billing zip code(postal code).

state string

Billing State information. Available if your billing address is in the United States(US) or Canada(CA). Please refer to Area Code.

street1 string

The street of the shipping address. (e.g. 123 Main street, 56 Le Loi street)

settings object

display_type string

You can select how the payment opens in your browser. One of P OR R. if not sent, P is senty by default.
  1. P

    : Pop-up

  2. R

    : Replace

autoclose string

You can control how the browser closes the payment window when the payment is completed.
One of Y OR N. if not sent, N is senty by default.
  1. Y

    : Go to the merchant page.

  2. N

    : Go to the completion page of the payment (default)

site_foreign_currency string

Required to show the amount in the currency set by the customer on the merchant site.

* If you used the payment_method parameter, you can only send a P000(Credit Card).

* When using DCC at a merchant, only DCC supported currencies can be displayed in the payment window.
DCC supported currencies can be found in DCC Currency Codes.

* The price is based on the real-time exchange rate inquired through the Eximbay DCC Provider.
After the card information is finally entered, it may be changed to the currency of the card issuance country.

call_from_app string

Classification of client environment. One of Y OR N. If parameter is sent by empty, N is sent to the default.

  1. Y

    : App(iOS, AOS) evironment

  2. N

    : Web browser environment (default)

call_from_scheme string

The App URL Scheme required to return from an external app to the merchant app.

issuer_country string

This parameter is required to use domestic payment with send KR at a merchant who use global payment.

ostype string

This is the client environment that opens the payment window. If parameter is sent by empty, P is sent to the default.

  1. P

    : PC (default)

  2. M

    : Mobile

4. Verify the payment

To prevent forgery, merchants can send the response parameter as it is to the payment verification API to check whether it matches the fgkey sent as a response from the Eximbay server.

The parameter that the Eximbay server responds to as statusurl is sent in the form of a query string as shown below.

                
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
                
              

Please send the parameters that were answered by the query string to the payment verification API request parameters. Once the validation is completed with the payment verification API, the payment will be completed.

Request
      
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"
		    }'
      
    
      
        RestTemplate restTemplate = new RestTemplate();
  
        HttpHeaders headers = new HttpHeaders();
        headers.add("Content-Type", "application/json");
        headers.add("Authorization", "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=");
        
        URI url = URI.create("https://api-test.eximbay.com/v1/payments/verify");
        
        String body = "{\n" +
        "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"
        			        "}";
        
        HttpEntity<String> entity = new HttpEntity<>(body, headers);
        ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);
        
        System.out.println(response.getBody());
      
    
      
        <?php
        $url = 'https://api-test.eximbay.com/v1/payments/verify';
        $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"
        }';
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo='));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_POST, 1);
        
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        $response  = curl_exec($ch);
        
        echo $response;
        curl_close($ch);
        ?>
      
    
      
 import requests
  import json
  
  url = "https://api-test.eximbay.com/v1/payments/verify"
  headers = {
  "Authorization": "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=",
  "Content-Type": "application/json"
  }
  
  request = {
  "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"
  }
  response = requests.post(url, headers=headers, data=json.dumps(request))
  
  print(response.text)
      
    
      
var request = require('request');
  var options = {
  'method': 'POST',
  'url': 'https://api-test.eximbay.com/v1/payments/verify',
  'headers': {
    'Authorization': 'Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "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"
  })
  
  };
  request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
  });
      
    
        
 string uri = "https://api-test.eximbay.com/v1/payments/verify";
  string body = "{\n" +
  "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"
  			        "}";
  
  WebClient webClient = new WebClient();
  webClient.Headers[HttpRequestHeader.ContentType] = "application/json";
  webClient.Headers[HttpRequestHeader.Authorization] = "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=";
  webClient.Encoding = UTF8Encoding.UTF8;
  string responseJSON = webClient.UploadString(uri, body);
  
  Console.Write(responseJSON);
        
    
        
 val restTemplate =  RestTemplate()
  val headers = HttpHeaders()
  headers.add("Content-Type", "application/json")
  headers.add("Authorization", "Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo=")
  
  var url = URI.create("https://api-test.eximbay.com/v1/payments/verify")
  
  val body = "{\n" +
  "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"
  		        "}"
  
  var entity = HttpEntity<String>(body, headers)
  var response = restTemplate.exchange(url, HttpMethod.POST, entity, String::class.java)
  
  println(response.body)
        
    

Response

If you receive 0000 with the rescode, the payment is successful.

                    
{
  	"rescode": "0000",
  	"resmsg": "Success",
  }