Integration Guide with Demo

Toss Payments Demo

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

Integration Guide with Demo

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

STEP 1. Merchant Checkout Page

Desktop Demo	Mobile Demo
00:00~00:04	00:00~00:04

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

JavaScript

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

STEP 2. Toss Payments Payment Window

Desktop Demo	Mobile Demo
00:05~00:17	00:05~00:10

On Toss Payments payment window, the customer will:

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

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

STEP 3. Card Company Payment Window

Desktop Demo	Mobile Demo
00:18~00:34	00:11~00:24

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

The QR code comes up on the desktop monitor. Card company apps offer a QR scanning screen, like the one shown below.
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.

STEP 4. Merchant result page

Desktop Demo	Mobile Demo
00:35~00:39	00:25~00:28

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.

JSON

{
  "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"
}