Integrate Payment APIs

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

• 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 a Payment object if successful. Provide the customer with the checkout.url to open the payment window.

  Returns an error object if unsuccessful.

Authorize payments to finalize the transaction.

• 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 a Payment object if successful. Provide the customer with the checkout.url to open the payment window.

  Returns an error object if unsuccessful.

Cancel payments. Full and partial cancellations are available.

• paymentKey 필수 · string
  

  The payment key. The maximum length is 200 characters.

• 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 a Payment object if successful. Check the cancels array for details.

  Returns an error object if unsuccessful.

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

• 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 a Payment object if successful.

  Returns an error object if unsuccessful. See the related errors.