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.
- Get your API key
- Authorize the API key.
- 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.
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
- 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 thecardCompany
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.
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 inrequestPayment()
. 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.
Payment Method | Description | Amount field in Response object | Example |
---|---|---|---|
Credit·Debit Card | The card that the customer has registered for the digital wallet service. | card.amount | Customers' Card registered in the Toss Pay service. |
Rechargeable payment method | A 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.amount | An 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.discountAmount | Toss Pay points, Kakao Pay points |
* 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.