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.

DemoSee a demo of the Toss Payments Payment Window

Prerequisites

Here are some prerequisites for integration.

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

1. Add the SDK, Initialize, and Open a Payment Window 🚀

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.

Direct Type Payment Window

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.

Get customer consent to the Toss Payments terms of service below before opening the direct type payment window.

* Terms & conditions of electronic financial transactions: https://pages.tosspayments.com/terms/user

* Agreement on Collection and Use of Personal Information: https://pages.tosspayments.com/terms/privacy/consent1privacy/consent1

* Agreement on Personal Information Provision to Third Parties: https://pages.tosspayments.com/terms/privacy/consent2privacy/consent2

Payment Information Parameters

  • 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.

For more payment methods and parameters, check out the Toss Payments Javascript SDK.

2. Request Payment Authorization

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.

Check Redirect URLs

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.

Call the Payment Authorization API

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.

3. Your Payment is Finished! 🎉

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.

4. Check the Digital Wallet Response

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.

Types of Payment Methods for Digital Wallet

Payment MethodDescriptionAmount field in Response objectExample
Credit·Debit CardThe card that the customer has registered for the digital wallet service.card.amountCustomers' Card registered in the Toss Pay service.
Rechargeable payment methodA payment method that the customer uses by recharging the amount of money, such as an account registered with an easy payment service or cash points.easyPay.amountAn account connected to Toss Pay, Kakao Pay, etc.
Accumulative payment method*The amount of points, coupons, and discounts earned by the customer using the payment service provided by the digital wallet company. This is used in combination with a card or rechargeable payment method.easyPay.discountAmountToss Pay points, Kakao Pay points

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

Case #1. Credit or Debit Cards

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.

Case #2. Card and Reward Points

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.

Case #3. Bank Account

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.

Case #4. Bank Account and Reward Points

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.

Case #5. Reward Points

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.

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기