Prerequisites
1. Add the SDK, Initialize, and Open a Payment Window 🚀
- Payment Information Parameters
2. Request Payment Authorization
- Check Redirect URLs
- Call the Payment Authorization API
3. Your Payment is Finished! 🎉
4. Check the Digital Wallet Response
- Types of Payment Methods for Digital Wallet

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.

DemoSee a demo of the Toss Payments Payment Window

Sample projectSee payment window sample projects

Prerequisites

Here are some prerequisites for integration.

Get your API key
Authorize the API key.
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.

HTML

<head>
  <script src="https://js.tosspayments.com/v1/payment"></script>
</head>
<body>
  <script>
    var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
    var tossPayments = TossPayments(clientKey) // Initialize with client key

    tossPayments
      .requestPayment('CARD', {
        // Payment method parameter
        // Payment information parameters
        amount: 15000,
        orderId: '9Y5kSA_PIt9kpUGUbEtQD',
        orderName: 'Toss T-Shirts',
        customerName: 'Tom Kim',
        successUrl: 'http://localhost:8080/success',
        failUrl: 'http://localhost:8080/fail',
        flowMode: 'DIRECT', // Directly open a card company or digital wallet's payment window
        easyPay: 'TOSSPAY', // Designate the digital wallet window
        //cardCompany: 'HYUNDAI' // Designate the card company window
      })
      .catch(function (error) {
        if (error.code === 'USER_CANCEL') {
          // Handling errors when a customer closes the payment window
        } else if (error.code === 'INVALID_CARD_COMPANY') {
          // Handling errors for invalid card codes
        }
      })
  </script>
</body>

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.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}

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.

Example

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"5JhXAzCQjuDvbL6ALZL06","amount":15000,"orderId":"k72T5lv7pB7wHC5ldxvCA"}'

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.

JSON

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "5JhXAzCQjuDvbL6ALZL06",
  "lastTransactionKey": "asbGxuQqFlrtzTnGDWFlZ",
  "orderId": "k72T5lv7pB7wHC5ldxvCA",
  "orderName": "Toss T-shirts",
  "status": "DONE",
  "requestedAt": "2022-08-17T15:38:47+09:00",
  "approvedAt": "2022-08-17T15:39:14+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": null,
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": {
    "provider": "TOSSPAY",
    "amount": 15000,
    "discountAmount": 0
  },
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
    "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=cno3Idq53AKHoXP%2BJnAWt70lTLYJHVytjcCu%2FhEIUd56LAMEmBlJ9FWaQinp0uZ1&ref=PX"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/5JhXAzCQjuDvbL6ALZL06/checkout"
  },
  "currency": "KRW",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0,
  "method": "EASYPAY"
}

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

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.

Example

JSON

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "94gplu2IiIeqSBl3Ju360",
  "status": "DONE",
  "lastTransactionKey": "wVbYJIiXDUi-p4o0m8pJf",
  "orderId": "xWgO8xvJM5HgjFaqgtFwi",
  "orderName": "Toss T-Shirts",
  //...
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "123456******7890",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "21974757",
    "useCardPoint": false,
    "cardType": "CREDIT",
    "ownerType": "PERSONAL",
    "acquireStatus": "READY",
    "amount": 15000
  },
  "easyPay": {
    "provider": "TOSSPAY",
    "amount": 0,
    "discountAmount": 0
  },
  //...
  "totalAmount": 15000
}

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.

Example

JSON

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "hmHTyYNyMSzxr0n8M1kG5",
  "status": "DONE",
  "lastTransactionKey": "OSh2XuFqr2wC37Ra6foIc",
  "orderId": "ma93JoCS1LAFtlHudfg3I",
  "orderName": "Toss T-Shirts",
  //...
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "123456******7890",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "21706400",
    "useCardPoint": false,
    "cardType": "CREDIT",
    "ownerType": "PERSONAL",
    "acquireStatus": "READY",
    "amount": 10000
  },
  "easyPay": {
    "provider": "TOSSPAY",
    "amount": 0,
    "discountAmount": 5000
  },
  //...
  "totalAmount": 15000
}

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.

Example

JSON

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "AjCkrrGf5wTGK7e97v8Qt",
  "status": "DONE",
  "lastTransactionKey": "S8uBREQQq2aYB_gm-HU-1",
  "orderId": "ma93JoCS1LAFtlHudfg3I",
  "orderName": "Toss T-Shirts",
  //...
  "card": null,
  "easyPay": {
    "provider": "TOSSPAY",
    "amount": 15000,
    "discountAmount": 0
  },
  //...
  "totalAmount": 15000
}

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.

Exmaple

JSON

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "",
  "status": "DONE",
  "lastTransactionKey": "",
  "orderId": "",
  "orderName": "Toss T-Shirts",
  //...
  "card": null,
  "easyPay": {
    "provider": "TOSSPAY",
    "amount": 10000,
    "discountAmount": 5000
  },
  //...
  "totalAmount": 15000
}

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.

JSON

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "",
  "status": "DONE",
  "lastTransactionKey": "",
  "orderId": "",
  "orderName": "Toss T-Shirts",
  //...
  "card": null,
  "easyPay": {
    "provider": "TOSSPAY",
    "amount": 0,
    "discountAmount": 15000
  },
  //...
  "totalAmount": 15000
}

.css-p1o082{width:calc(0.8em + 8px);height:0.8em;position:absolute;top:calc(50% - 0.4em);left:calc(-0.8em - 8px);padding-right:8px;opacity:0;-webkit-transition:opacity 0.2s ease-in-out;-webkit-transition:opacity 0.2s ease-in-out;transition:opacity 0.2s ease-in-out;}Integrate the Payment Window

Prerequisites

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

Payment Information Parameters

2. Request Payment Authorization

Check Redirect URLs

Call the Payment Authorization API

3. Your Payment is Finished! 🎉

4. Check the Digital Wallet Response

Types of Payment Methods for Digital Wallet

Case #1. Credit or Debit Cards

Case #2. Card and Reward Points

Case #3. Bank Account

Case #4. Bank Account and Reward Points

Case #5. Reward Points

Integrate the Payment Window