> 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). # Developing For service introduction and console setup instructions, please refer to the Toss Pay introduction document. Please follow the sequence below for the integration flow. 1. [Create payment](#_1-결제-생성하기) — Create a 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 the authenticated `payToken`token, approve the actual payment. 4. [Refund payment](#_4-결제-환불하기) — Refund the payment. 5. [Check payment status](#_5-결제-상태-조회하기) — Check the payment status and transaction. *** ### Prerequisites #### Console setup is required You must first complete the steps below before calling the API. 1. Please proceed with the subscription. 2. Please register the Toss Pay key values 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 from `userKey` value. | | `x-anon-key` | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)hash value obtained from | Please choose according to your purpose. * If you have already integrated Toss Login, or if you want to manage member information such as name and email together, use Toss Login. * If you want to identify only the user lightly without login integration, use the user identification key issuance feature. `x-anon-key`If you want to check in advance whether the (hash) is a valid value, [Please use the Identify Key Validation](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key#식별키-검증하기) 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, please set up an mTLS certificate on the server before calling it. For how to issue the certificate [mTLS certificate issuance method](https://developers-apps-in-toss.toss.im/documentation/integration/getting-started)please refer to {% endhint %} *** ### Testing When requesting payment creation `isTestPayment: true`By setting it, you can test payments in the sandbox environment. You do not need to configure it separately in the console, and you can test even before subscription. However, in the sandbox, only payment creation is possible, and actual approval processing is not supported. *** ### 1. Create payment Create a payment. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/make-payment` {% hint style="info" %} **Please be sure to check when using cash receipts** Partners that need cash receipt issuance must, when requesting payment creation, `cashReceipt: true`must be sent. `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`omit it or `false`if sent as {% endhint %} **Request headers** For the header that identifies the payment target, use one of the two below. Do not send both headers at once. | 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 from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info | | `x-anon-key` | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value. | **Request parameters** | Name | Type | Required | Description | | ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | orderNo | String | Y | **merchant's order number**It is. It must be unique for each merchant each time, and if duplicated, the payment creation request will fail. Numbers, letters, and special characters `_-:.^@`can be used only and must be within 50 characters. The same order number cannot be reused after buyer authentication is completed. Order numbers more than 2 years after initial creation also cannot be reused. | | productDesc | String | Y | **product description**It is. It cannot consist only of spaces, and backslash `\`and quotation marks `"`cannot be included, and the total must be within 255 characters. If Korean is included, please 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-free amount within the payment amount**It is. For taxable items, `0`please send it as | | amountTaxable | Integer | N | **taxable amount within the payment amount**It is. If you do not set it separately and send the tax-free amount as `0`won, the server calculates it automatically. | | amountVat | Integer | N | **VAT amount 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**It is. | | enablePayMethods | String | N | **payment method type variable**It is. - `TOSS_MONEY`: Only Toss Money displayed - `CARD`: Only card displayed - `null` or otherwise: displayed as the default payment method set for the store | | cashReceipt | boolean | N | **Whether cash receipt issuance is available**It is. When using the cash receipt feature `true`, when not in use `false`please send it. `null` If an abnormal value such as the same is sent, it is explicitly `false`processed as | | 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 installment (default) - `NOT_USE`: do not use installment | | isTestPayment | boolean | Y | If it is a sandbox payment request `true`, if it is a live app payment request `false`It is. | ``` 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 save 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 the process succeeded. Actual payment processing must be done 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 that authenticates Toss Pay payment. **`checkoutPayment`** **Signature** ```typescript function checkoutPayment(options: CheckoutPaymentOptions): Promise; ``` **Parameters** * **options** · Required · `CheckoutPaymentOptions` These are the options needed to open the payment window. **Return value** * `Promise` Returns a result including whether authentication succeeded. **Example** {% tabs %} {% tab title="js" %} ```js import { checkoutPayment } from '@apps-in-toss/web-framework'; async function handleCheckoutPayment() { try { // Replace this with the API endpoint that creates the payment in the actual implementation. const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json()); const { success, reason } = await checkoutPayment({ payToken }); if (success) { // Replace this with the API endpoint that executes the payment in the actual implementation. 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 needed 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 successfully authenticated in the Toss Pay payment window. **Signature** ```typescript interface CheckoutPaymentResult { success: boolean; reason?: string; } ``` **Properties** * **success** · Required · `boolean` Whether authentication succeeded. * reasonstring The reason if authentication failed. *** ### 3. Execute payment When the buyer completes payment authentication, the payment status is 'pending'. `payToken`With the pay token and order number, calling this API completes the actual approval and withdraws the amount from the buyer's payment method. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/execute-payment` **Request headers** For the header that identifies the payment target, use one of the two below. Do not send both headers at once. | 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 from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info | | `x-anon-key` | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value. | **Request parameters** | Name | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | | payToken | String | Y | Toss Pay token. | | orderNo | String | N | Merchant order number. | | isTestPayment | boolean | Y | `payToken`If it was issued in the sandbox `true`, if it was issued in the live app `false`It is. | ``` 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`: for real transactions, `TEST`: for testing | | orderNo | String | Approved product order number. | | amount | Integer | Product amount. | | approvalTime | String | Payment approval processing time. (yyyy-MM-dd HH:flag\_mm:ss) | | stateMsg | String | Status response text. In a normal response `"Payment complete"`comes back. | | discountedAmount | Integer | Discounted amount. If there is no discount applied, `0`comes back as. It includes the immediate discount and Toss Points used. | | paidAmount | Integer | Amount approved by payment method. The net approved amount after excluding the discount amount from the total amount. | | payMethod | String | Payment method. `TOSS_MONEY`: Toss Money, `CARD`: card | | payToken | String | This is the Toss Pay token. You must save and manage it. | | transactionId | String | Transaction ID. It can be used as a distinguishing value when calling the sales receipt or processing a refund. | | cardCompanyCode | String | Approved card company code. | | cardCompanyName | String | Approved card company name. | | cardAuthorizationNo | String | Card company approval number that the buyer can check. Available in live key payments. | | spreadOut | String | The card installment months selected by the user. For amounts under 50,000 won and lump-sum payments, `0`comes back as. | | noInterest | String | Whether card no-interest installment is applied. `true`: no-interest, `false`: normal | | salesCheckLinkUrl | String | Credit card sales receipt URL. | | cardMethodType | String | Card type. `CREDIT`: credit card, `CHECK`: debit card, `PREPAYMENT`: prepaid card | | cardNumber | String | Masked card number. The middle digits of the 16-digit card number 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. Partial 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 complete", "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** For the header that identifies the payment target, use one of the two below. Do not send both headers at once. | 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 from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info | | `x-anon-key` | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value. | **Request parameters** | Name | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | payToken | String | Y | Toss Pay token. | | reason | String | Y | Refund reason. Only Korean, numbers, 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`It is. | **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 | Amount approved by payment method. | | refundedAmount | Integer | Refund request amount. | | refundedDiscountAmount | Integer | The actual deducted discount amount from the refund request amount. | | refundedPaidAmount | Integer | The actual deducted payment-method amount 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. Check payment status You can check the transaction status and transactions of a created payment. You can also use this if you did not receive an approval or refund response. * Content-type: `application/json` * Method: `POST` * URL: `/api-partner/v1/apps-in-toss/pay/get-payment-status` **Request headers** For the header that identifies the payment target, use one of the two below. Do not send both headers at once. | 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 from `userKey`It is. [You can obtain it through](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)Get user info | | `x-anon-key` | string | Choose one | [User identification key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)obtained from `hash` value. | **Request parameters** | Name | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | | payToken | String | Y | Toss Pay token. | | orderNo | String | Y | Merchant order number. | | isTestPayment | boolean | Y | `payToken`If it was issued in the sandbox `true`, if it was issued in the live app `false`It is. | **Response** | Name | Type | Description | | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | mode | String | Payment environment. `LIVE`: for real transactions, `TEST`: for testing | | payToken | String | Toss Pay token. | | orderNo | String | This is the merchant order number linked to Toss Pay. | | payStatus | String | 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 of Toss Points used. | | paidAmount | Integer | Amount approved by payment method. | | refundableAmount | Integer | This is the refundable balance. | | amountTaxable | Integer | This is the taxable amount of the total payment. | | amountTaxFree | Integer | This is the tax-exempt amount of the total payment. | | amountVat | Integer | This is the VAT amount of the total payment. | | amountServiceFee | Integer | This is the service charge of the total payment. | | disposableCupDeposit | Integer | This is the disposable cup deposit. | | accountBankCode | String | This is a 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`: normal | | spreadOut | Integer | This is the card installment period 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 URL. | | cardCompanyName | String | Approved card company name. | | cardCompanyCode | Integer | This is the card issuer code. | | transactions | list | This is the transaction list. | | 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 amount remitted to the merchant for the requested transaction type. For refund requests, a negative amount is returned. | | discountedAmount | Integer | This is the discount amount applied for the requested transaction type. It includes instant discounts and Toss Point usage. | | pointAmount | Integer | This is the point amount for the requested transaction type. | | regTs | String | This is the request processing time. | | createdTs | String | Payment creation time. This is the time of the user's first payment request. | | paidTs | String | Payment completion 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 reference **Payment status list** | Value | Description | | ---------------------------- | ------------------------------ | | PAY\_STANDBY | Waiting for 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, the account information selected by the user is also sent. | Bank code (accountBankCode) | Bank name (accountBankName) | | --------------------------- | ------------------------------- | | 002 | Korea Development Bank | | 003 | Industrial Bank of Korea | | 004 | KB Kookmin Bank | | 005 | Hana Bank | | 007 | Suhyup Bank | | 011 | NH NongHyup Bank | | 020 | Woori Bank | | 023 | SC 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 | Forestry 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 Securities | | 266 | SK Securities | | 267 | Daishin Securities | | 269 | Hanwha Investment & Securities | | 270 | Hana Securities | | 271 | Toss Securities | | 278 | Shinhan Investment & Securities | | 279 | DB Financial Investment | | 280 | Eugene Investment | | 287 | Meritz Securities | | 888 | Toss Money | | 889 | Toss Point | **Card issuer code list** | Card issuer name | Card (acquiring company) code | | -------------------- | ----------------------------- | | Shinhan | 1 | | Hyundai | 2 | | Samsung | 3 | | Kookmin | 4 | | Lotte | 5 | | Hana | 6 | | Woori | 7 | | NongHyup | 8 | | Citi (not supported) | 9 | | BC | 10 | **Error code** | Value | Description | | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | | PAYMENT\_EXISTING\_PAYMENT | This payment already exists. | | COMMON\_INVALID\_API\_KEY | The apiKey is invalid. | | COMMON\_BREAK\_TIME\_OF\_BANK | It is currently bank maintenance time. Please use it after maintenance ends. | | [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.