Payment windows
목차

Start your payment window integration. Supported payment methods include card, digital wallets such as TossPay, NaverPay, SamsungPay, KakaoPay etc, transfer, virtual accounts, mobile phone, and gift certificates.

For card and digital wallet payments, choose a hosted or direct integration method. See the Integration type guide to learn about each method.

card


Integrate payment windows

Use the below API keys for your initial integration. If you sign up and log into the Toss Payments developer center, you will be issued a set of your own keys and access to test logs and webhooks.

API key

1. Request payment

Use the code below to open a payment window.

After initializing the SDK, call the requestPayment() method to open the payment window. For card and digital wallet payments, set the payment type parameter to CARD. To open a Toss Payments hosted window, set the flowMode parameter as DEFAULT. To open an app card or digital wallet window, set flowMode as DIRECT and use either the easyPay or cardCompany parameter to designate the specific payment method.

Toss Payments currently supports both version 1 and 2 of the SDK. The main difference between the two is that the many payment products that were separate SDKs in version 1 have been merged into a single SDK in version 2. We recommend using version 2 but if you need native mobile SDK support, please use version 1.

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

ConditionsLink
Terms & conditions for online financial transactionshttps://pages.tosspayments.com/terms/user
Personal information collection and usage agreementhttps://pages.tosspayments.com/terms/privacy/consent1privacy/consent1
Provision of personal information to 3rd partyhttps://pages.tosspayments.com/terms/privacy/consent2privacy/consent2

requestPayment() Parameters

For a complete list of parameters, see the Toss Payments SDK reference documentation.

  • method 필수 · string

    Payment method. Use CARD, VIRTUAL_ACCOUNT, MOBILE_PHONE, TRANSFER, CULTURE_GIFT_CERTIFICATE, BOOK_GIFT_CERTIFICATE, GAME_GIFT_CERTIFICATE, or FOREIGN_EASY_PAY.

  • amount 필수 · object

    Payment amount information.

  • value 필수 · number

    Payment amount.

  • currency 필수 · string

    Payment currency. FOREIGN_EASY_PAY or PayPal, currently only accepts USD. All other payment methods only accept KRW.

  • orderId 필수 · string

    Order ID that you generate. Generate a random string between 6 and 64 characters, using upper and lowercase letters, numerals, -, and _. No other special characters are allowed.

  • orderName 필수 · string

    Order name. Maximum length is 100 characters.

  • successUrl string

    The URL customers are redirected to upon payment request success. Check query parameters for paymentKey, orderId, and amount. The successUrl must include the origin; for example, https://www.example.com/success.

  • failUrl string

    The URL customers are redirected to upon payment request failure. Check query parameters for error codes and messages. The failUrl must include the origin; for example, https://www.example.com/fail.

  • card object

    Card payment information. Use when method is CARD.

  • flowMode string

    Payment window type. To open the hosted type window, use DEFAULT. To open the direct type window, input DIRECT and use the cardCompany or easyPay parameters.

  • cardCompany string

    Code of the card payment you want to open. For example, if you input HYUNDAI, the Hyundai Card payment window will open.

    * Only Korean card companies are accepted.

  • easyPay string

    Code of the digital wallet you want to open. For example, if you input TOSSPAY, the Toss Pay payment window will open.

    * Some digital wallet providers do not work in test environments.

  • useAppCardOnly boolean

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

    * Kookmin, Nonghyup, Lotte, Samsung, Sinhan, Woori, Hyundai provide AppCards.

  • appScheme string

    App scheme of your service. After the customer completes the payment on an mobile ISP app, this app scheme is used to redirect them back to your ap. Specify your store's app scheme like this: testapp://.

  • useInternationalCardOnly boolean

    Whether or not to accept international cards (Visa, MasterCard, JCB, UnionPay, AMEX). If true, a multilingual checkout window with Korean, English, Chinese, and Japanese language options will open.

2. Handle the redirect

Successful requests

If your payment request is successful, the client is redirected to the successUrl that you set with the requestPayment() method. The successUrl is followed by three query parameters.

The amount value of the query parameter should be the same as the amount you originally set during the payment request. If they are different, it may be due to a malicious attempt to change the amount on the client side. Stop the payment and ask the customer to re-attempt the purchase.

Save the paymentKey, amount, orderId values to your server. paymentKey is used for refunds, payment retrievals, and more.

Failed requests

If your payment request fails, the client is redirected to the failUrl that you set with the requestPayment() method. The failUrl is followed by three query parameters.

Cause of error

When the customer terminate the payment process. Because the payment is terminated before authentication, the orderId is not added as a query parameter.

Cause of error

When an error arises during the payment request or payment method authentication.

Solution

  • See the error message for details. Contract related inquiries should be direct to the Toss Payments customer center(1544-7772, support@tosspayments.com).

  • For other technical issues visit our Discord channel for help.

Cause of error

When the card information the customer has entered is incorrect or invalid.

Solution

  • See the error message for details.

3. Authorize the payment

Finally, authorize the payment to charge your customer's payment method. Encode your secret key and colon in base64 to use as the API authorization header.

Use the below terminal command to get the encoded auth header.

Add the base64 encoded secret key as the Auth header. Optionally, add the Accept-Language header as below to get your responses in English. Fill in the request body with the paymentKey, amount, and orderId retrieved from the successUrl.

4. See the API response

When your authorization succeeds, you will get a 200 OK with the Payment object. Check the below Payment object fields.

  • method should have the payment method that your customer selected
  • card holds the card details for a card payment, transfer for a transfer payment and so on. Check the appropriate field for the customer's payment details. However if the customer has paid with a digital wallet, it may be necessary to check both card and easyPay fields.
  • virtualAccount payments can be simulated using the test payment logs menu if you are logged in.
  • If you can't find the field you're looking for, check the API version.

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