TossPayments Demo

This guide goes through a demo of the TossPayments Payment Window SDK and explains how to authenticate and authorize a credit card payment.

Play the PC or mobile demo video and check time stamp for each step.

• 💻 TossPayments PC Demo
• 📱 TossPayments Mobile Demo

When the customer hits the "Pay" button, call the SDK method below to open a TossPayments Payment Window.

tossPayments.requestPayment('CARD', {
  amount: 50000,
  orderId: 'TossPaymentsTest26287062',
  orderName: 'Toss T-Shirts',
  customerName: 'Tom Kim',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})

On TossPayments payment window, the customer will:

1. Agree to the terms and conditions
2. Select the card company or bank they wish to pay with, and
3. Set the card installment period

Then, the customer will be redirected to the card company payment window for authentication.

In the demo, the customer is redirected to the Samsung Card payment window, where they need to authenticate their card information. Authentication is most commonly done through the card company app. Below is the PC procedure.

1. The QR code comes up on the PC monitor. Card company apps offer a QR scanning screen, like the one shown below.

   

2. When the customer scan the QR code using the card company app, payment information is sent to the card company app. The customer checks the payment information and enters a biometric authentication or PIN number to complete authentication. (The customer has already registered payment methods on the card company app.)

   • In addition to using the card company app, there are other methods for authentication, such as entering all card information (16 digits, cvc..). However still using card company app is most popular way in Korea.

On mobile, it will be automatically redirected from Web or App to card company's app. You need to integrate an card app to authenticate the cardholder-specific payment method when opening the card payment window in a mobile webview instead of a browser. See the list of card App URL Schemes and additional logic required for integration on the Integrate WebView page.

After authentication, the customer is redirected to successUrl or failUrl set in Step 1. If authentication is successful, then web page will redirect to successUrl with key-value(authentication information) data in its query string parameters.

https://localhost:8080/success?paymentKey=5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6&orderId=TossPaymentsTest26287062&amount=50000

Authorization completes the payment. Use the paymentKey, orderId, and amount values from the successUrl as the Payment Authorization API request data as below.

curl --request POST \
    --url https://api.tosspayments.com/v1/payments/confirm \
    --header 'Authorization: Basic {{api Key}}' \
    --header 'Content-Type: application/json' \
    --data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6","orderId":"TossPaymentsTest26287062","amount":50000}'

A successful API call returns a JSON-encoded Payment object.

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6-rzzQzk3tm",
  "status": "DONE",
  "lastTransactionKey": "wh_MbwYWWfc9rhnqxVuMN",
  "orderId": "TossPaymentsTest26287062",
  "orderName": "Toss T-Shirts",
  "requestedAt": "2022-06-08T15:40:09+09:00",
  "approvedAt": "2022-06-08T15:40:49+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "12345678****789*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "CREDIT",
    "ownerType": "PERSONAL",
    "acquireStatus": "READY",
    "amount": 15000
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
  "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/CF1YbsQcktc-rzzQzk3tm/checkout"
  },
  "currency": "KRW",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0,
  "method": "CARD"
}

If the API call fails, then it returns an error code and message. Check the Error Code page for more details.