Javascript SDK
IMP.request_pay(
  {
    pg: "kcp",
    pay_method: "card",
    merchant_uid: "{Merchant created Order ID}", // Example: order_no_0001
    name: "Order name: Test payment request",
    amount: 14000,
    buyer_email: "iamport@siot.do",
    buyer_name: "John Doe",
    buyer_tel: "010-1234-5678",
    buyer_addr: "Shinsa-dong, Gangnam-gu, Seoul",
    buyer_postcode: "123-456",
    language: "ko", // default: ko (Korean)
    m_redirect_url: "{Mobile only - URL to redirect to after payment approval}", // Example: https://www.my-service.com/payments/complete/mobile
  },
  function (rsp) {
    // callback logic
    //* ...Omitted... *//
  },
);

Key parameter description

pg * string

PG code

• If not specified and this is the only PG setting that exists, default PG is automatically set.
• If there are multiple PG settings, set to kcp.

pay_method * string

Payment method code

merchant_uid * string

Order ID

Must be unique for each request.

amount * integer

Payment amount

Must be an integer (not string).

To open non-authenticated payment window, specify the customer_uid parameter. After getting a billing key from this window, you can request payment using the billing key.

Javascript SDK
IMP.request_pay(
  {
    pg: "kcp_billing",
    pay_method: "card", // only 'card' supported.
    merchant_uid: "{Merchant created Order ID}", // Example: issue_billingkey_monthly_0001
    name: "Initial billing key request",
    amount: 0, // For display purpose only (no payment approval).
    customer_uid: "{Unique ID for the card (billing key)}", // Required (Example: gildong_0001_1234)
    buyer_email: "johndoe@gmail.com",
    buyer_name: "John Doe",
    buyer_tel: "02-1234-1234",
    m_redirect_url: "{redirect URL}", // Example: https://www.my-service.com/payments/complete/mobile (for mobile only)
  },
  function (rsp) {
    if (rsp.success) {
      alert("Success");
    } else {
      alert("Failed");
    }
  },
);

Key parameter description

pg * string

PG code

• If not specified and this is the only PG setting that exists, default PG is automatically set.
• If there are multiple PG settings, set to kcp_billing.

customer_uid * string

Credit card billing key

Billing key to be mapped 1:1 with the user-entered credit card information.

amount * Integer

Payment amount

Amount to display in the payment window, but actual payment approval is not processed. (To request payment, use the REST API with the customer_uid.)\

Request payment with billing key (customer_uid)

After successfully getting the billing key, the billing key is stored on the i'mport server mapped 1:1 with the specified customer_uid. For security reasons, the server cannot directly access the billing key. Subsequent payments can be requested by calling the non-authenticated payment request REST API with the customer_uid as follows:

sever-side
curl -H "Content-Type: application/json" \
     -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/again

You can use i'mport REST API to request billing key, request payment, and schedule payment.

Request one-time payment

To request a one-time payment, use the key-in REST API POST /subscribe/payments/onetime. The card information is not saved during this process.

curl -H "Content-Type: application/json" \
     -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/onetime

Request billing key

To request a billing key, use the billing key request REST API POST /subscribe/customers/{customer_uid}.

curl -H "Content-Type: application/json" \
     -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \
     https://api.iamport.kr/subscribe/customers/your-customer-unique-id

Request billing key + initial payment

To request a billing key and initial payment, use the key-in REST API POST /subscribe/payments/onetime.

• customer_uid : required for saving the billing key.

curl -H "Content-Type: application/json" \
     -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/onetime

Request payment with billing key

After successfully getting the billing key and making the initial payment, the billing key is stored on the i'mport server mapped 1:1 with the specified customer_uid. For security reasons, the server cannot directly access the billing key. Subsequent payments can be requested by calling the repeat pay REST API (POST /subscribe/payments/again) with the customer_uid as follows:

curl -H "Content-Type: application/json" \
     -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/again

For detailed information, refer to:

javascript
{
  "display": {
    "card_quota": [6] // Display up to 6 months installment plans
  }
}

Parameters

• card_quota :
  • []: Only immediate pay
  • 2,3,4,5,6: immediate, 2, 3, 4, 5, 6 month installment plans\

Example of allowing up to 3 months installment plans

javascript
{
  "card": {
    "direct": {
      "code": "367",
      "quota": 3
      // When want to use points of credit card
      // quota: 80 = 80(Hyundai Card Point installment) + 0(pay all at once)
      // quota: 93 = 80(Hyundai Card Point installment) + 13(number of installments)
      // quota: 60 = 60(Other Card Point installment) + 0(pay all at once)
      // quota: 63 = 60(Other Card Point installment) + 3(number of installments)
    }
  }
}

Parameters

• code: Credit card code (string)

• quota: Installment plan. For immediate, set to 0. If you want to use points of credit card, you need to add the point installment per credit card^[1] to number of installments (integer)

  ^[1] point installment per credit card

  Point of Credit Card	Point Installment
  Hyundai M	+80
  Kookmin	+60
  BC	+60
  Samsung	+60
  Hana/KEB	+60
  Lotte	+60
  Shinhan	+60
  NongHyup	+60
  Citi	+60
  Woori	+60

javascript
{
  "card": {
    "detail": [
      { "card_code": "*", "enabled": false }, // Disable all credit cards
      { "card_code": "366", "enabled": true } // Enable specific credit card
    ]
  }
}

Parameters

• card_code: Credit card code (string)
• enabled: Option to enable the credit card (boolean)

Set the following parameter to only expose app cards for authenticated payments.

request_pay()
{
  "appCard": true // Set to true to only expose app cards.
}

To use the gift certificate payment method, set the merchant assigned user ID as follows:

javascript SDK
{
  "bypass": {
    "shop_user_id": "ABCD123" // Merchant user ID (20 bytes)
  }
}

Example of paying with Cultureland gift certificate

IMP.request_pay({
  pg: "kcp.{Site code for gift certificate use}",
  pay_method: "cultureland", //Gift certificate
  merchant_uid: "A00021-TEST",
  name: "Carrots 10kg",
  amount: 1004,
  buyer_email: "iamport@chai.finance",
  buyer_name: "iamport tech support",
  buyer_tel: "010-1234-5678",
  buyer_addr: "Shinsa-dong, Gangnam-gu, Seoul",
  buyer_postcode: "123-456",
  bypass: {
    shop_user_id: "abaddd", // Merchant user ID
  },
});

For escrow payment, set the escrow parameter to true. To bundle products in the shopping cart when making an escrow payment request, pass the item-related information as an additional parameter (kcpProducts).

kcpProducts is an object array consisting of the following four required properties:

amount is not related or compared with the payment amount (param.amount).

• orderNumber : Order ID
• name : Product name
• quantity : Product quantity
• amount : Product price

JavaScript SDK
IMP.request_pay({
  pg: "kcp",
  escrow: true, // For escrow payment
  kcpProducts: [
    {
      orderNumber: "xxxx",
      name: "Product A",
      quantity: 3,
      amount: 1000,
    },
    {
      orderNumber: "yyyy",
      name: "Product B",
      quantity: 2,
      amount: 3000,
    },
  ],
  //* ...Omitted... *//
});