> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/monetization/toss-pay/development.md). # Develop Please refer to the Toss Pay introduction document for the service overview and console setup instructions. Follow the sequence below for the integration flow. 1. [Create payment](#_1-결제-생성하기) — Create the payment on the server and `payToken`issue the token. 2. [Authenticate payment](#_2-결제-인증하기) — Open the payment window with the SDK and perform user authentication. 3. [Execute payment](#_3-결제-실행하기) — With authentication completed, `payToken`approve the actual payment with it. 4. [Refund payment](#_4-결제-환불하기) — Refund the payment. 5. [Check payment status](#_5-결제-상태-조회하기) — Check payment status and transaction. *** ### Prerequisites #### Console setup is required Before calling the API, you must complete the procedures below first. 1. Please proceed with the subscription process. 2. Please register the Toss Pay key value in the console. For subscription/setup instructions, [Toss Pay introduction](https://developers-apps-in-toss.toss.im/documentation/common/monetization/toss-pay) please refer to the document. #### Identify the payment target user Toss Pay identifies the payment target using one of the two methods below. Do not pass both values at the same time; choose only one. | Category | Issuance method | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-toss-user-key` | [Toss Login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained with `userKey` value. | | `x-anon-key` | [Issue user identification key](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)This is the hash value obtained with | Please choose according to your purpose. * If you have already integrated Toss Login, or want to manage it together with member information such as name and email, use Toss Login. * If you want to identify users lightly without login integration, use the user identification key issuance feature. `x-anon-key`If you want to check in advance whether (hash) is a valid value, [Check identification key](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key#식별키-검증하기) use the API. *** ### Basic information | Item | Value | | --------------------- | -------------------------------------- | | Base URL | `https://pay-apps-in-toss-api.toss.im` | | Server authentication | mTLS (client certificate) | | Content-Type | `application/json` | {% hint style="info" %} **mTLS certificate is required for server-to-server communication** The Toss Pay payment API is server-to-server communication called from the partner server to the Apps in Toss server. For security, set up an mTLS certificate on the server before calling it. For how to issue a certificate, [How to issue an mTLS certificate](https://developers-apps-in-toss.toss.im/documentation/integration/getting-started)please refer to. {% endhint %} *** ### Test When requesting payment creation `isTestPayment: true`If set, you can test payments in the sandbox environment. You don't need to configure it separately in the console, and you can test it even before subscription. However, in the sandbox, only payment creation is possible; actual approval processing is not supported. *** ### 1. Create payment Create the payment. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/make-payment` {% hint style="info" %} **Please make sure to check when using cash receipts** Partners that need to issue cash receipts must `cashReceipt: true`be sure to pass. `cashReceipt`can only be set at the time of payment creation, and after payment is completed, the cash receipt issuance target cannot be changed. `cashReceipt`omitting it or `false`sending it as {% endhint %} **Request headers** Use one of the two headers below to identify the payment target. Do not pass both headers at the same time. | Name | Type | Required | Description | | ----------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-toss-user-key` | string | Choose one | [Toss Login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained with `userKey`. [Get user information](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)can be obtained through. | | `x-anon-key` | string | Choose one | [Issue user identification key](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained with `hash` value. | **Request parameters** | Name | Type | Required | Description | | ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | orderNo | String | Y | **merchant's order number**is the merchant's order number. It must be unique per merchant each time, and if duplicated, the payment creation request will fail. Only numbers, English letters, and special characters are allowed, and it must be within 50 characters. The same order number cannot be reused after buyer authentication is complete. Order numbers that were created more than 2 years ago also cannot be reused. `_-:.^@`can only be used, and it must be within 50 characters. The same order number cannot be reused after buyer authentication is complete. Order numbers that were created more than 2 years ago also cannot be reused. | | productDesc | String | Y | **Product description**It cannot be set to only spaces, and cannot include backslash `\`and quotation marks `"`and must be within 255 characters total. If it includes Korean, use UTF-8 encoding. | | amount | Integer | Y | **Total payment amount**It is. All parameters related to amounts must be passed as numbers. | | amountTaxFree | Integer | Y | **Tax-exempt amount within the payment amount**It is. If it is a taxable item, `0`pass it as | | amountTaxable | Integer | N | **Taxable amount within the payment amount**It is. If you do not set it separately and send the tax-exempt amount as `0`won, the server will calculate it automatically. | | amountVat | Integer | N | **VAT within the payment amount**It is. If there is no value, it is calculated by dividing the taxable amount by 11 and rounding up to the first decimal place. | | amountServiceFee | Integer | N | **Service fee within the payment amount**. | | enablePayMethods | String | N | **Payment method selection variable**It is. - `TOSS_MONEY`: show Toss Money only - `CARD`: show card only - `null` or otherwise: show the default payment method configured for the store | | cashReceipt | boolean | N | **Whether cash receipt issuance is possible**It is. If using the cash receipt feature `true`, if not using it `false`pass `null` If you pass an abnormal value as above, it will be explicitly handled as `false`. | | cashReceiptTradeOption | String | N | **Cash receipt issuance type**It is. - `GENERAL`: General (default) - `CULTURE`: Culture expenses - `PUBLIC_TP`: Transportation expenses | | installment | String | N | **Installment restriction type**It is. - `USE`: Use installments (default) - `NOT_USE`: Do not use installments | | isTestPayment | boolean | Y | For sandbox payment requests, `true`, for live app payment requests, `false`. | ``` curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/make-payment' \ --header 'Content-Type: application/json' \ --header 'x-toss-user-key: 1234' \ --data '{ "orderNo": "test-20250417-3", "productDesc": "test02", "amount": 10, "amountTaxFree": 0, "cashReceipt": false, "isTestPayment": true }' ``` **Response parameters** | Name | Type | Description | | -------- | ------ | --------------------------------------------------------------------------------------------------- | | payToken | String | **Toss Pay token**It is. A unique token value is generated each time. You must store and manage it. | ```json { "resultType": "SUCCESS", "success": { "payToken": "string" } } ``` *** ### 2. Authenticate payment `TossPay.checkoutPayment`opens the Toss Pay payment window and performs user authentication. When authentication is complete, it returns whether it succeeded. The actual payment processing must be carried out separately on the server after authentication succeeds. **`TossPay`** `TossPay`is an object that groups Toss Pay payment-related functions. **Signature** ```typescript TossPay: { checkoutPayment: typeof checkoutPayment; } ``` **Properties** * checkoutPaymenttypeof checkoutPayment A function for authenticating Toss Pay payments. **`checkoutPayment`** **Signature** ```typescript function checkoutPayment(options: CheckoutPaymentOptions): Promise; ``` **Parameters** * **options** · Required · `CheckoutPaymentOptions` The options required to open the payment window. **Return value** * `Promise` Returns the result including whether authentication succeeded. **Example** {% tabs %} {% tab title="js" %} ```js import { checkoutPayment } from '@apps-in-toss/web-framework'; async function handleCheckoutPayment() { try { // In a real implementation, replace this with the API endpoint that creates the payment. const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json()); const { success, reason } = await checkoutPayment({ payToken }); if (success) { // In a real implementation, replace this with the API endpoint that executes the payment. await fetch('/my-api/payment/execute', { method: 'POST', body: JSON.stringify({ payToken }), headers: { 'Content-Type': 'application/json' }, }); console.log('Payment successful'); } else { console.log('Authentication failed:', reason); } } catch (error) { console.error('An error occurred during payment authentication:', error); } } ``` {% endtab %} {% tab title="React" %} ```tsx import { checkoutPayment } from '@apps-in-toss/web-framework'; import { Button } from '@toss/tds-mobile'; function TossPayButton() { async function handlePayment() { try { const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json()); const { success, reason } = await checkoutPayment({ payToken }); if (success) { await fetch('/my-api/payment/execute', { method: 'POST', body: JSON.stringify({ payToken }), headers: { 'Content-Type': 'application/json' }, }); console.log('Payment successful'); } else { console.log('Authentication failed:', reason); } } catch (error) { console.error('An error occurred during payment authentication:', error); } } return ; } ``` {% endtab %} {% tab title="React Native" %} ```tsx import { TossPay } from '@apps-in-toss/framework'; import { Button } from '@toss/tds-react-native'; function TossPayButton() { async function handlePayment() { try { const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json()); const { success, reason } = await TossPay.checkoutPayment({ payToken }); if (success) { await fetch('/my-api/payment/execute', { method: 'POST', body: JSON.stringify({ payToken }), headers: { 'Content-Type': 'application/json' }, }); console.log('Payment successful'); } else { console.log('Authentication failed:', reason); } } catch (error) { console.error('An error occurred during payment authentication:', error); } } return ; } ``` {% endtab %} {% endtabs %} **`CheckoutPaymentOptions`** `CheckoutPaymentOptions`These are the options required when opening the Toss Pay payment window. **Signature** ```typescript interface CheckoutPaymentOptions { payToken: string; } ``` **Properties** * **payToken** · Required · `string` The payment token. **`CheckoutPaymentResult`** `CheckoutPaymentResult`Whether the user succeeded in authentication in the Toss Pay payment window. **Signature** ```typescript interface CheckoutPaymentResult { success: boolean; reason?: string; } ``` **Properties** * **success** · Required · `boolean` Whether authentication succeeded. * reasonstring The reason why authentication failed. *** ### 3. Execute payment When the buyer completes payment authentication, the payment status is 'pending'. `payToken`When you call this API with the token and the order number, the actual approval is completed and the amount is withdrawn from the buyer's payment method. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/execute-payment` **Request headers** Use one of the two headers below to identify the payment target. Do not pass both headers at the same time. | Name | Type | Required | Description | | ----------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-toss-user-key` | string | Choose one | [Toss Login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained with `userKey`. [Get user information](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)can be obtained through. | | `x-anon-key` | string | Choose one | [Issue user identification key](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained with `hash` value. | **Request parameters** | Name | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------- | | payToken | String | Y | It is a Toss Pay token. | | orderNo | String | N | It is the merchant order number. | | isTestPayment | boolean | Y | `payToken`If it was issued in the sandbox `true`, if it was issued in the live app `false`. | ``` curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/execute-payment' \ --header 'Content-Type: application/json' \ --header 'x-toss-user-key: 1234' \ --data '{ "payToken": "test-20250417-3", "orderNo": "test02", "isTestPayment": true }' ``` **Response** | Name | Type | Description | | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mode | String | Payment environment. `LIVE`: production, `TEST`: test | | orderNo | String | It is the approved product order number. | | amount | Integer | It is the product amount. | | approvalTime | String | Payment approval processing time. (yyyy-MM-dd HH:flag\_mm:ss) | | stateMsg | String | This is the status response text. In the case of a normal response, `"Payment completed"`is returned. | | discountedAmount | Integer | The discounted amount. `0`If no discount is applied, it is returned as | | paidAmount | Integer | The approved amount for the payment method. The net approved amount excluding the discount amount from the total amount. | | payMethod | String | Payment method. `TOSS_MONEY`: Toss Money, `CARD`: card | | payToken | String | It is a Toss Pay token. You must store and manage it. | | transactionId | String | Transaction ID. Can be used as an identifier when calling the sales receipt or processing a refund. | | cardCompanyCode | String | Approved card company code. | | cardCompanyName | String | Approved card company name. | | cardAuthorizationNo | String | The card issuer authorization number that the buyer can check. It is available in live key payments. | | spreadOut | String | The card installment months selected by the user. For amounts under 50,000 won and one-time payments, `0`is returned. | | noInterest | String | Whether card no-interest installment is applied. `true`: no interest, `false`: regular | | salesCheckLinkUrl | String | Credit card sales receipt call URL. | | cardMethodType | String | Card type. `CREDIT`: credit card, `CHECK`: debit card, `PREPAYMENT`: prepaid card | | cardNumber | String | The masked card number. In a 16-digit card number, the middle digits are masked. | | cardUserType | String | Card user type. `PERSONAL`: personal card, `PERSONAL_FAMILY`: family card, `CORP_PERSONAL`: corporate designated payment account employee, `CORP_PRIVATE`: corporate shared, `CORP_COMPANY`: corporate designated payment account company (Hana Card only) | | cardNum4Print | String | The last 4 digits of the card selected by the user. | | cardBinNumber | String | Card BIN number. | | cashReceiptMgtKey | String | Cash receipt management number identifier. If this field is present, you can distinguish whether a cash receipt is issued. | | accountBankCode | String | Bank code. In the case of Toss Money payments, pass the bank code defined by Toss. | | accountBankName | String | Bank name. | | accountNumber | String | Account number. Some masking is included. | | msg | String | Explanation message when the response is not successful. | | errorCode | String | Error code. | ```json { "resultType": "SUCCESS", "success": { "code": 0, "mode": "TEST", "orderNo": "20250417-2", "amount": 10, "approvalTime": "2025-04-17 12:32:10", "stateMsg": "Payment completed", "discountedAmount": 0, "paidAmount": 10, "payMethod": "TOSS_MONEY", "payToken": "O1NZck9XME8ureeVJVJP67", "transactionId": "45a77cf4-5577-4d5c-8827-4d4dd328bf12", "cardCompanyCode": null, "cardCompanyName": null, "cardAuthorizationNo": null, "spreadOut": null, "noInterest": null, "salesCheckLinkUrl": null, "cardMethodType": null, "cardNumber": null, "cardUserType": null, "cardNum4Print": null, "cardBinNumber": null, "cashReceiptMgtKey": null, "accountBankCode": "092", "accountBankName": "Toss Bank", "accountNumber": "100******094", "msg": null, "errorCode": null } } ``` *** ### 4. Refund payment Refund the payment to the buyer. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/refund-payment` **Request headers** Use one of the two headers below to identify the payment target. Do not pass both headers at the same time. | Name | Type | Required | Description | | ----------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-toss-user-key` | string | Choose one | [Toss Login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained with `userKey`. [Get user information](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)can be obtained through. | | `x-anon-key` | string | Choose one | [Issue user identification key](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained with `hash` value. | **Request parameters** | Name | Type | Required | Description | | ------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | payToken | String | Y | It is a Toss Pay token. | | reason | String | Y | Refund reason. Only Korean, numbers, English letters, and special characters `_ - : . ^ @ ( ) [ ] # / ! % ? &`are allowed. | | isTestPayment | boolean | Y | `payToken`If it was issued in the sandbox `true`, if it was issued in the live app `false`. | **Response** | Name | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | refundNo | String | Refund number. | | approvalTime | String | Refund processing time. (yyyy-MM-dd HH:flag\_mm:ss) | | cashReceiptMgtKey | String | Cash receipt management number identifier. | | refundableAmount | Integer | Refundable amount. | | discountedAmount | Integer | Discounted amount. | | paidAmount | Integer | Approved amount for the payment method. | | refundedAmount | Integer | Refund request amount. | | refundedDiscountAmount | Integer | The discount amount actually deducted from the refund request amount. | | refundedPaidAmount | Integer | The payment method amount actually deducted from the refund request amount. | | payToken | String | Refunded payment token. | | transactionId | String | Transaction ID. | | cardMethodType | String | Card type. `CREDIT`: credit card, `CHECK`: debit card, `PREPAYMENT`: prepaid card | | cardNumber | String | Masked card number. | | cardUserType | String | Card user type. `PERSONAL`: personal card, `PERSONAL_FAMILY`: family card, `CORP_PERSONAL`: corporate designated payment account employee, `CORP_PRIVATE`: corporate shared, `CORP_COMPANY`: corporate designated payment account company (Hana Card only) | | cardNum4Print | String | The last 4 digits of the card selected by the user. | | cardBinNumber | String | Card BIN number. | | accountBankCode | String | Bank code. In the case of Toss Money payments, pass the bank code defined by Toss. | | accountBankName | String | Bank name. | | accountNumber | String | Masked account number. | ```json { "resultType": "SUCCESS", "success": { "refundNo": "string", "approvalTime": "string", "cashReceiptMgtKey": "string", "refundableAmount": 0, "discountedAmount": 0, "paidAmount": 0, "refundedAmount": 0, "refundedDiscountAmount": 0, "refundedPaidAmount": 0, "payToken": "string", "transactionId": "string", "cardMethodType": "string", "cardNumber": "string", "cardUserType": "string", "cardNum4Print": "string", "cardBinNumber": "string", "accountBankCode": "string", "accountBankName": "string", "accountNumber": "string" } } ``` *** ### 5. Retrieve payment status You can retrieve the transaction status and transactions of a created payment. This can also be used when approval or refund responses are not received. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/get-payment-status` **Request headers** Use one of the two headers below to identify the payment target. Do not pass both headers at the same time. | Name | Type | Required | Description | | ----------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-toss-user-key` | string | Choose one | [Toss Login](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)obtained with `userKey`. [Get user information](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)can be obtained through. | | `x-anon-key` | string | Choose one | [Issue user identification key](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained with `hash` value. | **Request parameters** | Name | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------- | | payToken | String | Y | It is a Toss Pay token. | | orderNo | String | Y | It is the merchant order number. | | isTestPayment | boolean | Y | `payToken`If it was issued in the sandbox `true`, if it was issued in the live app `false`. | **Response** | Name | Type | Description | | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | mode | String | Payment environment. `LIVE`: production, `TEST`: test | | payToken | String | It is a Toss Pay token. | | orderNo | String | This is the merchant order number linked to Toss Pay. | | payStatus | String | This is the payment status. | | payMethod | String | Payment method. `TOSS_MONEY`: Toss Money, `CARD`: card | | amount | Integer | This is the total payment amount sent by the merchant. | | discountedAmount | Integer | Discounted amount. | | discountAmountV2 | Integer | This is the amount of instant discount applied. | | paidPointV2 | Integer | This is the amount spent using Toss Points. | | paidAmount | Integer | Approved amount for the payment method. | | refundableAmount | Integer | This is the refundable balance. | | amountTaxable | Integer | This is the taxable amount of the total payment amount. | | amountTaxFree | Integer | This is the non-taxable amount of the total payment amount. | | amountVat | Integer | This is the VAT amount of the total payment amount. | | amountServiceFee | Integer | This is the service fee within the total payment amount. | | disposableCupDeposit | Integer | This is the disposable cup deposit. | | accountBankCode | String | This is the bank code. | | accountBankName | String | Bank name. | | accountNumber | String | Masked account number. | | card | Object | This is card information. | | noInterest | Boolean | Whether card no-interest installment is applied. `true`: no interest, `false`: regular | | spreadOut | Integer | This is the card installment months selected by the user. | | cardAuthorizationNo | String | This is the card issuer approval number that the buyer can check. | | cardMethodType | String | Card type. `CREDIT`: credit card, `CHECK`: debit card, `PREPAYMENT`: prepaid card | | cardUserType | String | Card user type. | | cardNumber | String | Masked card number. | | cardBinNumber | String | Card BIN number. | | cardNum4Print | String | The last 4 digits of the card selected by the user. | | salesCheckLinkUrl | String | Credit card sales receipt call URL. | | cardCompanyName | String | Approved card company name. | | cardCompanyCode | Integer | This is the card issuer code. | | transactions | list | This is the list of transaction records. | | stepType | String | This is the requested transaction type. `PAY`: payment, `REFUND`: refund | | transactionId | String | This is the transaction ID. We recommend using it for transaction reconciliation. | | paidAmount | Integer | This is the payment method amount for the requested transaction type. | | transactionAmount | Integer | This is the merchant-delivered amount for the requested transaction type. For refund requests, a negative amount is returned. | | discountedAmount | Integer | This is the discount amount applied to the requested transaction type. It includes instant discounts and Toss Points used. | | pointAmount | Integer | This is the point amount for the requested transaction type. | | regTs | String | This is the request processing time. | | createdTs | String | This is the payment creation time. It is the time of the user's first payment request. | | paidTs | String | This is the payment completion processing time. | ```json { "resultType": "SUCCESS", "success": { "mode": "string", "payToken": "string", "orderNo": "string", "payStatus": "string", "payMethod": "string", "amount": 0, "discountedAmount": 0, "discountAmountV2": 0, "paidPointV2": 0, "paidAmount": 0, "refundableAmount": 0, "amountTaxable": 0, "amountTaxFree": 0, "amountVat": 0, "amountServiceFee": 0, "disposableCupDeposit": 0, "accountBankCode": "string", "accountBankName": "string", "accountNumber": "string", "card": { "noInterest": true, "spreadOut": 0, "cardAuthorizationNo": "string", "cardMethodType": "string", "cardUserType": "string", "cardNumber": "string", "cardBinNumber": "string", "cardNum4Print": "string", "salesCheckLinkUrl": "string", "cardCompanyName": "string", "cardCompanyCode": 0 }, "transactions": [ { "stepType": "string", "transactionId": "string", "paidAmount": 0, "transactionAmount": 0, "discountedAmount": 0, "pointAmount": 0, "regTs": "string" } ], "createdTs": "string", "paidTs": "string" } } ``` *** ### 6. Code cleanup **Payment status list** | Value | Description | | ---------------------------- | ------------------------------ | | PAY\_STANDBY | Awaiting payment | | PAY\_APPROVED | Buyer authentication completed | | PAY\_CANCEL | Payment canceled | | PAY\_PROGRESS | Payment in progress | | PAY\_COMPLETE | Payment completed | | REFUND\_PROGRESS | Refund in progress | | REFUND\_SUCCESS | Refund successful | | SETTLEMENT\_COMPLETE | Settlement complete | | SETTLEMENT\_REFUND\_COMPLETE | Refund settlement complete | **Bank code list** For Toss Money payments, also send the account information selected by the user. | Bank code (accountBankCode) | Bank name (accountBankName) | | --------------------------- | ------------------------------- | | 002 | KDB Industrial Bank | | 003 | IBK Industrial Bank of Korea | | 004 | KB Kookmin Bank | | 005 | KEB Hana Bank | | 007 | Suhyup Bank | | 011 | NH NongHyup Bank | | 020 | Woori Bank | | 023 | Standard Chartered Bank | | 027 | Citibank | | 031 | Daegu Bank | | 032 | Busan Bank | | 034 | Gwangju Bank | | 035 | Jeju Bank | | 037 | Jeonbuk Bank | | 039 | Gyeongnam Bank | | 045 | MG Community Credit Cooperative | | 048 | Credit Union | | 050 | Savings Bank | | 064 | Forest Cooperative | | 071 | Post Office | | 081 | Hana Bank | | 088 | Shinhan Bank | | 089 | K Bank | | 090 | KakaoBank | | 092 | Toss Bank | | 103 | SBI Savings Bank | | 218 | KB Securities | | 230 | Mirae Asset Securities | | 238 | Mirae Asset Securities | | 240 | Samsung Securities | | 243 | Korea Investment & Securities | | 247 | NH Investment & Securities | | 261 | Kyobo Securities | | 262 | HI Investment & Securities | | 263 | Hyundai Motor Securities | | 264 | Kiwoom Securities | | 265 | eBEST Investment & Securities | | 266 | SK Securities | | 267 | Daishin Securities | | 269 | Hanwha Investment & Securities | | 270 | Hana Securities | | 271 | Toss Securities | | 278 | Shinhan Securities | | 279 | DB Financial Investment | | 280 | Eugene Investment & Securities | | 287 | Meritz Securities | | 888 | Toss Money | | 889 | Toss Points | **Card issuer code list** | Card issuer name | Card (acquirer) code | | -------------------- | -------------------- | | Shinhan | 1 | | Hyundai | 2 | | Samsung | 3 | | Kookmin | 4 | | Lotte | 5 | | Hana | 6 | | Woori | 7 | | NongHyup | 8 | | Citi (not supported) | 9 | | BC (BC) | 10 | **Error code** | Value | Description | | -------------------------------------------------------------- | --------------------------------------------------------------------------------- | | PAYMENT\_EXISTING\_PAYMENT | This is a payment that already exists. | | COMMON\_INVALID\_API\_KEY | The apiKey is invalid. | | COMMON\_BREAK\_TIME\_OF\_BANK | The bank is currently under maintenance. Please use it after maintenance is over. | | [Other error codes](https://docs-pay.toss.im/guide/error-code) | | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/monetization/toss-pay/development.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.