Integrate the Payment Window

This guide explains how to open a direct type payment window for card and digital wallet(e-wallet) payments. A digital wallet is an online service where customers pre-register their credit cards or bank accounts to make online transactions.

The payment window supports all types of online card payments, including card company apps and ISP payments, and most commonly used Korean digital wallets, such as TossPay, NaverPay, SamsungPay, LPay, KakaoPay, Payco, and SSGPay.

Here are some prerequisites for integration.

1. Get your API key
2. Authorize the API key.
3. Check the response parameters(Payment Object)

Add the Payment Window SDK in the script tag of your checkout page and initialize it using your client key. Then, use the requestPayment('CARD', {PAYMENT_INFORMATION}) method to open a payment window.

The first parameter is payment methods. Use CARD to open a card company or digital wallet payment window.

The second parameter is payment information. Enter the required parameters such as purchase amount, and then fix the flowMode parameter as DIRECT. To open a card company’s payment window, use the cardCompany parameter. To open a digital wallet window, use the easyPay parameter.

If successful, the payment window for the designated card or digital wallet will open as above. Request authorization to complete the payment.

Otherwise, a payment will not open. Check the error in the catch block of the Promise. See the list of possible SDK errors.

• amount 필수 · number
  

  The payment amount.

• orderId 필수 · string
  

  The order ID. Generate a random string between 6 and 64 characters, using upper and lowercase letters, numerals, -, and _. (No other special characters are allowed.)

• orderName 필수 · string
  

  The name of the order. E.g., bottled water and 1 other item. The maximum length is 100 characters.

• successUrl 필수 · string
  

  The URL customer are redirected to when the payment succeeds. Required values for payment authorization are sent through query parameters. It must include the origin. For example, https://www.example.com/success.

• failUrl 필수 · string
  

  The URL customer are redirected to when the payment fails. Error codes and messages are sent through query parameters. It must include the origin. For example, https://www.example.com/fail.

• flowMode string
  

  The type of the payment window. To open the direct type payment window, input DIRECT and use the cardCompany oreasyPay.

• cardCompany string
  

  The card company code. Refer to card company codes. For example, if you input HYUNDAI, the Hyundai Card payment window will open.

  * Only Korean card companies are accepted. Overseas cards cannot be used.

• easyPay string
  

  The digital wallet code. For example, if you input TOSSPAY, the Toss Pay payment window will open. Refer to digital wallet codes.

  * KakaoPay and Payco payments are not available in test settings.

• useAppCardOnly boolean
  

  Whether or not to open the card company app. If true, the customer can only pay through the card company app.

  * The following companies have card company apps: Kookmin, Nonghyup, Lotte, Samsung, Sinhan, Woori, Hyundai.

• appScheme string
  

  Used when returning to your store from the mobile ISP app. Specify your store's app scheme, such as testapp://.

• useInternationalCardOnly boolean
  

  Whether or not to accept international cards (Visa, MasterCard, JCB, UnionPay, AMEX). If true, a multilingual checkout window will open.

If the payment request succeeds, the browser will be redirected to successUrl. Check the query parameters in the URL and request authorization. If the payment request fails, the brower is redireced to failUrl. Check the query parameters in the URL to see the error code and message.

The successUrl has three query parameters: paymentKey, orderId, and amount. You can call the payment authorization API using the redirect URL query parameters.

• paymentKey: The payment key used for authorization, cancellation and other post-payment operations.
• orderId: The order ID. It should be the same as the parameter requestPayment() method when a payment window is triggered.
• amount: The amount that is going to be charged. Check whether this amount is the same as the requested amount value in requestPayment(). If the two values differ, resend the payment request.

Use the paymentKey, orderId, and amount values from the successUrl as the Payment Authorization API request data. The basic authentication header is your secret key and a colon, encoded in base64.

The Payment Authorization API must be called within 10 minutes of being redirected to successUrl.

Congratulations, if you got a HTTP 200 OK response, you've successfully completed a payment. Check the Payment Object response to make sure your payment method and amount are correct.

Response fields vary depending on the API version. If you can’t find a specific field in the response, check your API version through the Toss Payments Developer Center and update the version accordingly.

With a digital wallet payment, the Payment Object response can change depending on how the customer paid. Refer to the cases below to see how.

* Accumulative payment methods can be used in combination with cards or rechargeable payment methods.

Customers can register credit or debit cards on their digital wallet.

If a customer pays 15,000 KRW with a credit card registered in TossPay, the totalAmount should be equal to the card.amount.

Let's say a customer pays 10,000 KRW with their credit card registered in TossPay and 5,000 KRW with TossPoint, a type of reward point offered in most digital wallets that can be used like cash.

The total amount of the order (totalAmount) should be equal to the sum of the card.amount and easyPay.discountAmount.

If a customer pays with a bank account connected to TossPay, the total amount of the order (totalAmount) should be equal to easyPay.amount. In this case, you only need to check the easyPay object of the response.

A customer pays 10,000 KRW with a bank account connected to TossPay and 5,000 KRW with TossPoint, a type of reward point offered in most digital wallets that can be used like cash.

The total amount of the order (totalAmount) should be equal to the sum of the easyPay.amount and easyPay.discountAmount. In this case, you only need to check the easyPay object of the response.

If a customer pays 15,000 KRW with TossPoint, The total amount of the order (totalAmount) should be equal to easyPay.discountAmount. In this case, you only need to check the easyPay object of the response.