Payment APIs
목차

The Payment APIs are essential to integrating Toss Payments, whether you are only using our APIs or our SDKs. Use your test API key starting with test_ to use the APIs in test mode. In test mode, live data or funds are not affected.

This guide walks you through a select number of Payment APIs in English. To see the full list of Toss Payment APIs, see the Core API reference page (Korean).


Overview

Authorization

The Toss Payments Core APIs all use Basic authorization. Add a colon to the end of your secret key. Encode the secret key and colon in base 64. Add the encoded secret key and colon to the Basic auth header as below.

Authorization: Basic base64('{SECRET_KEY}:')

English Header

Add the header below to get the API response in English.

Accept-Language: en-US

Idempotency

Use the idempotency key header to ensure sensitive API requests only occur once. Requests sent with the same idempotency key will return the same response even on multiple requests. The idempotency key should be a unique and random value up to 300 characters long. An idempotency key is valid for 15 days.

Idempotency-Key: {IDEMPOTENCY_KEY}

Create Payment

POST/v1/payments

Create a payment window. Use this API as an alternative to the SDK.

Request Body Parameters

  • method 필수 · string

    Specify the customer's payment method with a set of enumerated values. CARD is used for both card and digital wallet payments.

  • amount 필수 · number

    Amount to charge the customer.

  • orderId 필수 · string

    Order ID for payment. Generate a random string between 6 and 64 characters, using upper and lowercase letters, numerals, -, and _. (No other special characters are allowed.)

  • orderName 필수 · string

    Name of an order. E.g., bottled water and 1 other item. The maximum length is 100 characters.

  • returnUrl 필수 · string

    URL where the customer is redirected after the payment. The origin must be included.

  • flowMode string

    Mode of the payment window. DEFAULT is the default setting and returns the Toss Payments window.

    Set the paramter to DIRECT to return the card or digital wallet payment window directly. When set to direct mode, either one of the easyPay or cardCompany parameters are required.

  • easyPay string

    Digital wallet provider code.

  • cardCompany string

    Card company code.

  • confirmationMethod string

    Option to process authentication and authorization for the payment simultaneously or separately. MANUAL is the default setting.

    • MANUAL: Payment is authenticated. To authorize the payment, call the Authorize Payment API.
    • AUTOMATIC: Payment is authenticated and authorized.
  • appScheme string

    App scheme of your app. This is used to redirect the customer back to your app after payment is completed on an external payment app.

Returns


  • Returns a Payment object if successful. Provide the customer with the checkout.url to open the payment window.

    Returns an error object if unsuccessful.

Request
curl --request POST \
--url https://api.tosspayments.com/v1/payments \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"method": "CARD", "amount": 1000, "orderId": "", "orderName": "Toss T-shirts", "returnUrl": "http://localhost:8080/returnUrl", "confirmationMethod": "AUTOMATIC"}'
Response
JSON
{
"mId": "tvivarepublica",
"lastTransactionKey": null,
"paymentKey": "dJv2eBNjG0Poxy1XQL8RxPJv7qkAQKV7nO5Wmlg96RKwZz4Y",
"orderId": "",
"orderName": "Toss T-shirts",
"taxExemptionAmount": 0,
"status": "READY",
"requestedAt": "2023-12-05T11:24:27+09:00",
"approvedAt": null,
"useEscrow": null,
"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": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": null,
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/dJv2eBNjG0Poxy1XQL8RxPJv7qkAQKV7nO5Wmlg96RKwZz4Y/checkout"
},
"currency": "KRW",
"totalAmount": 1000,
"balanceAmount": 1000,
"suppliedAmount": 909,
"vat": 91,
"taxFreeAmount": 0,
"method": null,
"version": "2022-11-16"
}

Authorize Payment

POST/v1/payments/confirm

Authorize payments to finalize the transaction.

Request Body Parameters

  • paymentKey 필수 · string

    A unique key given to each payment, issued by Toss Payments. The maximum length is 200 characters.

  • orderId 필수 · string

    Order ID for payment. Generate a random string between 6 and 64 characters, using upper and lowercase letters, numerals, -, and _. (No other special characters are allowed.)

  • amount 필수 · number

    Amount to charge the customer.

Returns


  • Returns a Payment object if successful. Provide the customer with the checkout.url to open the payment window.

    Returns an error object if unsuccessful.

Request
curl --request POST \
--url https://api.tosspayments.com/v1/payments/confirm \
--header 'Authorization: Basic dGVzdF9za19hQlg3emsyeWQ4eW9Yd29KMGdxVng5UE9McUtROg==' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"","orderId":"","amount":15000}'
Response
JSON
{
"mId": "tosspayments",
"version": "2022-11-16",
"lastTransactionKey": "B7103F204998813B889C77C043D09502",
"paymentKey": "",
"orderId": "",
"orderName": "Toss T-shirt",
"currency": "KRW",
"method": "CARD",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"amount": 15000,
"issuerCode": "61",
"acquirerCode": "31",
"number": "12341234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"receipt": {
"url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_YPBal2vxj81ORdDjOPwV5RQgOAND/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
},
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"taxExemptionAmount": 0
}

Cancel Payment

POST/v1/payments/{paymentKey}/cancel

Cancel payments. Full and partial cancellations are available.

Path Parameters

  • paymentKey 필수 · string

    The payment key. The maximum length is 200 characters.

Request Body Parameters

  • cancelReason 필수 · string

    The reason for canceling payments. The maximum length is 200 characters.

  • cancelAmount 필수 · number

    The amount to be canceled. The default value is 0.

  • refundReceiveAccount obejct

    The information of customer's refund account information. This parameter is required only for virtual account payments. You don’t need this object when canceling payments with other payment methods.

  • bank 필수 · string

    The bank code of customers’ accounts for refunds. Please refer to the bank codes.

  • accountNumber 필수 · string

    The account number to receive refunds. Only numbers should be entered. (- is not allowed.) The maximum length is 20 characters.

  • holderName 필수 · string

    The name of account holder. The maximum length is 60 characters.

  • taxFreeAmount number

    The tax-exempted amount out of the amount to be canceled. The default value is 0.

    * This parameter will work only for duty-free stores or stores selling both tax-free and taxable products. Stores selling taxable products cannot use this function. For more information, please refer to how to take care of taxes.

  • currency number

    The tax-exempted amount out of the amount to be canceled. The default value is 0.

    * This parameter will work only for duty-free stores or stores selling both tax-free and taxable products. Stores selling taxable products cannot use this function. For more information, please refer to how to take care of taxes.

  • refundableAmount number ・ deprecated

    This is for the available amount for refunds. Use this parameter to make sure you don't cancel more than the actual refundable amount.

    If the available amount for refunds is different from refundableAmount, an error is sent without processing the cancellation.

    * Deprecated parameter. Use IDEMPOTENCY_KEY in request header to cancel payments safely.

Returns

Request
curl --request POST \
--url https://api.tosspayments.com/v1/payments/dxRrMScPUSvrdmfYps_UG/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"cancelReason":"Customer wants refund"}'
Response
JSON
{
"mId": "tosspayments",
"version": "2022-11-16",
"lastTransactionKey": "U2b2cx9DfHNEodrT4vb88",
"paymentKey": "dxRrMScPUSvrdmfYps_UG",
"orderId": "sd7bqJRAFeNxm91hKfqGO",
"orderName": "Toss T-Shirts",
"currency": "KRW",
"method": "CARD",
"status": "CANCELED",
"requestedAt": "2022-01-01T11:31:29+09:00",
"approvedAt": "2022-01-01T11:31:51+09:00",
"useEscrow": false,
"cultureExpense": false,
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/dxRrMScPUSvrdmfYps_UG/checkout"
},
"card": {
"issuerCode": "33",
"acquirerCode": "31",
"number": "12341234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "CREDIT",
"ownerType": "PERSONAL",
"acquireStatus": "READY"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": [
{
"cancelReason": "Customer wants refund",
"canceledAt": "2022-01-01T11:32:04+09:00",
"cancelAmount": 10000,
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"refundableAmount": 0,
"easyPayDiscountAmount": 0,
"transactionKey": "8B4F646A829571D870A3011A4E13D640",
"receiptKey": "V4AJ6AhSWsGN0RocizZQlagPLN8s2IahJLXpfSHzQBTKoDG7"
}
],
"secret": null,
"type": "NORMAL",
"easyPay": "TOSSPAY",
"country": "KR",
"failure": null,
"totalAmount": 10000,
"balanceAmount": 0,
"suppliedAmount": 0,
"vat": 0,
"taxFreeAmount": 0,
"taxExemptionAmount": 0
}

Keyed Transactions

POST/v1/payments/key-in

In keyed transactions, customers manually enter a card number. Keyed transactions require separate terms. Contact Toss Payments to use this API.

Request Body Parameters

  • amount 필수 · integer

    The amount to be paid.

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

  • cardNumber 필수 · string

    The card number. The maximum length is 20 characters.

  • cardExpirationYear 필수 · string

    The card expiration year.

  • cardExpirationMonth 필수 · string

    The card expiration month.

  • cardPassword string

    The first two digits of the card password (PIN).

  • orderName 필수 · string

    The name of an order. E.g., bottled water and 1 other item. The maximum length is 100 characters.

  • customerIdentityNumber 필수 · string

    The card holder information. This string has 6 digits of the card holder’s date of birth (YYMMDD) or 10 digits of a business registration number.

  • cardInstallmentPlan integer

    The monthly installment period. You can configure the monthly installment period manually. You can enter values between 2 and 12. Entering 0 will trigger a one-time payment, not an installment.

  • useFreeInstallmentPlan boolean

    Whether or not to apply an interest-free installment plan supported by the card company. The default value is false. If the value is true, an interest-free installment plan will be applied for the months set at cardInstallmentPlan.

    * The interest-free installment plan fees incurred by this parameter is paid by the store.

  • taxFreeAmount integer

    This is the tax-exempted amount out of the amount to be canceled. The default value is 0 for any missing parameters.

    * This parameter will work only for duty-free stores or stores selling both tax-free and taxable products. Stores selling taxable products cannot use this function. For more information, please refer to how to take care of taxes.

  • customerEmail string

    The customer’s email address. Customers will be alerted about their payment result through this email. The maximum length is 100 characters.

  • customerName string

    The customer’s name. The maximum length is 100 characters.

  • vbv string

    This is used for the 3D Secure(3DS) authentication when customers are making card payments overseas. It is a required object if you have to send the 3DS authentication result.

  • cavv string

    The authentication value for the 3DS authentication session

  • xid string

    The transaction ID.

  • eci string

    The code value for the 3DS authentication result.

Returns

Request
curl --request POST \
--url https://api.tosspayments.com/v1/payments/key-in \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"amount":15000,"orderId":"","orderName":"Toss T-Shirts","customerName":"Tom Kim","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerIdentityNumber":"881212"}'
Response
JSON
{
"mId": "tosspayments",
"version": "2022-11-16",
"lastTransactionKey": "B7103F204998813B889C77C043D09502",
"paymentKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"amount": 15000,
"issuerCode": "61",
"acquirerCode": "31",
"number": "12341234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"receipt": {
"url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
},
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"taxExemptionAmount": 0
}
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기