> 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/api/en/toss-pay.md). # Toss Pay ## Create a payment > Create a payment.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through the error codes of the connected internal system as is. Treat undocumented \`errorCode\` as a failure and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"MakePaymentRequest":{"description":"This is the request body for creating a Toss Pay payment.","properties":{"amount":{"description":"This is the total payment amount.","format":"int64","maxLength":7,"type":"integer"},"amountServiceFee":{"description":"This is the service charge amount within the payment amount.","format":"int64","maxLength":7,"type":"integer"},"amountTaxFree":{"description":"This is the tax-exempt amount within the payment amount. If it is a taxable product, send 0.","format":"int64","maxLength":7,"type":"integer"},"amountTaxable":{"description":"This is the taxable amount within the payment amount. If you do not set a separate tax amount and send the tax-exempt amount as 0 won, the Toss Pay server automatically calculates the tax and VAT.","format":"int64","maxLength":7,"type":"integer"},"amountVat":{"description":"This is the VAT amount within the payment amount. If the value is missing, the taxable amount to be refunded is divided by 11, then rounded up to one decimal place.","format":"int64","maxLength":7,"type":"integer"},"cashReceipt":{"description":"This indicates whether a cash receipt can be issued. If null, it will not be issued.","type":"boolean"},"cashReceiptTradeOption":{"description":"This is the cash receipt issuance type. It is one of CULTURE (culture expenses) / GENERAL (general, default) / PUBLIC\\_TP (transportation expenses).","maxLength":10,"type":"string"},"enablePayMethods":{"description":"These are the available payment methods. You can use TOSS\\_MONEY/CARD or null.","maxLength":100,"type":"string"},"installment":{"description":"This is the installment restriction type. It is one of USE (use installments, default) / NOT\\_USE (do not use installments).","maxLength":10,"type":"string"},"isTestPayment":{"description":"False for sandbox, true for live app. If true, a real payment is made.","type":"boolean"},"orderNo":{"description":"This is the merchant's product order number. You can use numbers, letters, and special characters (\\_-:.^@).","maxLength":50,"type":"string"},"productDesc":{"description":"This is the product description. Please be careful with encoding if it includes Korean characters.","maxLength":255,"type":"string"}},"required":["amount","amountTaxFree","isTestPayment","orderNo","productDesc"],"type":"object"},"TossApiSuccessMakePaymentResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/MakePaymentResponse"}},"required":["resultType","success"],"type":"object"},"MakePaymentResponse":{"description":"This is the response to the Toss Pay payment creation request.","properties":{"payToken":{"description":"This is the Toss Pay token. It is a unique token value each time, and the merchant must store and manage this value.","maxLength":30,"type":"string"}},"required":["payToken"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/make-payment":{"post":{"description":"Create a payment.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through the error codes of the connected internal system as is. Treat undocumented `errorCode` as a failure and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"makePayment","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakePaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessMakePaymentResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessMakePaymentResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"The payment creation request was processed successfully."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Create a payment","tags":["toss-pay"]}}}} ``` ## Execute payment > Request approval for a payment that has completed payment authentication.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through the error codes of the connected internal system as is. Treat undocumented \`errorCode\` as a failure and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"ExecutePaymentRequest":{"description":"This is the request body for an approved payment that has been user-authenticated.","properties":{"isTestPayment":{"description":"False for sandbox, true for live app. If true, a real payment is made.","type":"boolean"},"orderNo":{"description":"This is the merchant's product order number. You can use numbers, letters, and special characters (\\_-:.^@).","maxLength":50,"type":"string"},"payToken":{"description":"This is the Toss Pay token. It is the token value of the payment to approve.","maxLength":30,"type":"string"}},"required":["isTestPayment","payToken"],"type":"object"},"TossApiSuccessExecutePaymentResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/ExecutePaymentResponse"}},"required":["resultType","success"],"type":"object"},"ExecutePaymentResponse":{"description":"This is the payment approval request response.","properties":{"accountBankCode":{"description":"This is the bank code. Returned only when the payment is made with Toss Money (account).","type":"string"},"accountBankName":{"description":"This is the bank name. Returned only when the payment is made with Toss Money (account).","type":"string"},"accountNumber":{"description":"This is the account number. It is partially masked and returned only when the payment is made with Toss Money (account).","type":"string"},"amount":{"description":"This is the total payment amount.","format":"int32","type":"integer"},"approvalTime":{"description":"This is the time when the payment was approved. (yyyy-MM-dd HH:flag\\_mm:ss format)","type":"string"},"cardAuthorizationNo":{"description":"This is the card approval number. Returned only for card payments.","type":"string"},"cardBinNumber":{"description":"This is the card BIN number. This value is provided by the card company, may be masked, and is returned only for card payments.","type":"string"},"cardCompanyCode":{"description":"This is the card company code. Returned only for card payments.","format":"int32","type":"integer"},"cardCompanyName":{"description":"This is the card company name. Returned only for card payments.","type":"string"},"cardMethodType":{"description":"This is the card type. It is one of CREDIT (credit card)/CHECK (debit card)/PREPAYMENT (prepaid card), and is returned only for card payments.","type":"string"},"cardNum4Print":{"description":"The last 4 digits of the card selected by the user. Returned only for card payments.","type":"string"},"cardNumber":{"description":"This is the masked card number. Returned only for card payments.","type":"string"},"cardUserType":{"description":"This is the card user type. It is one of PERSONAL (self-owned card)/PERSONAL\\_FAMILY (family card)/CORP\\_PERSONAL (employees of a corporate-designated payment account)/CORP\\_PRIVATE (corporate shared)/CORP\\_COMPANY (company of a corporate-designated payment account, Hana Card only), and is returned only for card payments.","type":"string"},"cashReceiptMgtKey":{"description":"This is the identifier for the cash receipt management number. Returned only when the payment is made with Toss Money (account).","type":"string"},"code":{"description":"This is the result code of payment approval processing. 0 for success, -1 for failure.","format":"int32","type":"integer"},"discountedAmount":{"description":"This is the payment amount after discounts are applied.","format":"int32","type":"integer"},"errorCode":{"description":"This is the error code returned when payment fails. It is returned when code is -1.","type":"string"},"mode":{"description":"Indicates the environment in which the payment was processed. One of NORMAL or TEST.","type":"string"},"msg":{"description":"This is the message containing the reason for failure when payment fails. It is returned when code is -1.","type":"string"},"noInterest":{"description":"This indicates whether it is interest-free installments. Returned only for card payments.","type":"boolean"},"orderNo":{"description":"This is the merchant's requested product order number.","type":"string"},"paidAmount":{"description":"This is the amount actually approved through the payment method.","format":"int32","type":"integer"},"payMethod":{"description":"This is the payment method. It takes CARD or TOSS\\_MONEY.","type":"string"},"payToken":{"description":"This is the token that identifies this payment.","type":"string"},"salesCheckLinkUrl":{"description":"This is the sales slip confirmation URL. Returned only for card payments.","type":"string"},"spreadOut":{"description":"This is the number of installment months. If 0, it is a one-time payment, and is returned only for card payments.","format":"int32","type":"integer"},"stateMsg":{"description":"This is a message describing the payment processing status.","type":"string"},"transactionId":{"description":"This is the transaction ID that identifies the transaction.","type":"string"}},"required":["amount","approvalTime","code","discountedAmount","mode","orderNo","paidAmount","payMethod","payToken","stateMsg","transactionId"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/execute-payment":{"post":{"description":"Request approval for a payment that has completed payment authentication.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through the error codes of the connected internal system as is. Treat undocumented `errorCode` as a failure and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"executePayment","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutePaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessExecutePaymentResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessExecutePaymentResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"The payment approval request was processed successfully."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Execute payment","tags":["toss-pay"]}}}} ``` ## Check payment status > You can retrieve the payment status requested by the user.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through the error codes of the connected internal system as is. Treat undocumented \`errorCode\` as a failure and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"PaymentStatusRequest":{"description":"These are the request parameters for payment status inquiry.","properties":{"isTestPayment":{"description":"Indicates whether this is a test payment.","type":"boolean"},"orderNo":{"description":"This is the order number. When making the request, either this value or `payToken` is required.","type":"string"},"payToken":{"description":"This is the key that identifies the payment. When making the request, either this value or `orderNo` is required.","type":"string"}},"required":["isTestPayment"],"type":"object"},"TossApiSuccessPaymentStatusResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/PaymentStatusResponse"}},"required":["resultType","success"],"type":"object"},"PaymentStatusResponse":{"description":"This is the response information for payment status inquiry.","properties":{"accountBankCode":{"description":"If it is an account payment, this is the bank code.","type":"string"},"accountBankName":{"description":"If it is an account payment, this is the bank name.","type":"string"},"accountNumber":{"description":"This is the account number.","type":"string"},"amount":{"description":"This is the total payment amount.","format":"int32","type":"integer"},"amountServiceFee":{"description":"This is the service fee amount.","format":"int32","type":"integer"},"amountTaxFree":{"description":"This is the tax-exempt amount.","format":"int32","type":"integer"},"amountTaxable":{"description":"This is the taxable amount.","format":"int32","type":"integer"},"amountVat":{"description":"This is the VAT amount.","format":"int32","type":"integer"},"card":{"$ref":"#/components/schemas/CardInfo","description":"This is card payment information."},"createdTs":{"description":"This is the time the payment was created (ISO 8601 format).","type":"string"},"discountAmountV2":{"description":"This is the discount amount applied by the latest discount system.","format":"int32","type":"integer"},"discountedAmount":{"description":"This is the amount after discount is applied.","format":"int32","type":"integer"},"disposableCupDeposit":{"description":"This is the disposable cup deposit amount.","format":"int32","type":"integer"},"mode":{"description":"Indicates the payment processing environment. It is one of NORMAL or TEST.","type":"string"},"orderNo":{"description":"This is the order number.","type":"string"},"paidAmount":{"description":"This is the amount actually paid by the user.","format":"int32","type":"integer"},"paidPointV2":{"description":"This is the amount paid with rewards/points.","format":"int32","type":"integer"},"paidTs":{"description":"This is the time the payment was completed (ISO 8601 format).","type":"string"},"payMethod":{"description":"This is the payment method. E.g., CARD, ACCOUNT\\_TRANSFER","type":"string"},"payStatus":{"description":"This is the payment status. E.g., DONE, CANCELLED, FAILED, etc.","type":"string"},"payToken":{"description":"This is the key that identifies the payment.","type":"string"},"refundableAmount":{"description":"This is the amount currently refundable.","format":"int32","type":"integer"},"transactions":{"description":"This is the list of transactions by payment processing stage.","items":{"$ref":"#/components/schemas/TransactionInfo"},"type":"array"}},"required":["amount","amountServiceFee","amountTaxFree","amountTaxable","amountVat","createdTs","discountAmountV2","discountedAmount","disposableCupDeposit","mode","orderNo","paidAmount","paidPointV2","paidTs","payMethod","payStatus","payToken","refundableAmount","transactions"]},"CardInfo":{"description":"This is detailed information about card payments.","properties":{"cardAuthorizationNo":{"description":"This is the card approval number.","type":"string"},"cardBinNumber":{"description":"This is the card BIN number.","type":"string"},"cardCompanyCode":{"description":"This is the card company code.","format":"int32","type":"integer"},"cardCompanyName":{"description":"This is the card company name.","type":"string"},"cardMethodType":{"description":"This is the card payment method.","type":"string"},"cardNum4Print":{"description":"The last 4 digits of the card selected by the user.","type":"string"},"cardNumber":{"description":"This is the masked card number.","type":"string"},"cardUserType":{"description":"This indicates whether it is personal or corporate.","type":"string"},"noInterest":{"description":"This indicates whether the payment is interest-free installments.","type":"boolean"},"salesCheckLinkUrl":{"description":"This is the sales slip URL.","type":"string"},"spreadOut":{"description":"This is the number of installment months.","format":"int32","type":"integer"}},"required":["cardAuthorizationNo","cardBinNumber","cardCompanyCode","cardCompanyName","cardMethodType","cardNum4Print","cardNumber","cardUserType","noInterest","salesCheckLinkUrl","spreadOut"]},"TransactionInfo":{"description":"This is transaction information by payment processing stage.","properties":{"discountedAmount":{"description":"This is the discount amount applied at that stage.","format":"int32","type":"integer"},"paidAmount":{"description":"This is the actual payment amount at that stage.","format":"int32","type":"integer"},"pointAmount":{"description":"This is the amount of points used at that stage.","format":"int32","type":"integer"},"regTs":{"description":"This is the transaction registration time (ISO 8601 format).","type":"string"},"stepType":{"description":"This is the payment processing stage. E.g., INIT, PAID","type":"string"},"transactionAmount":{"description":"This is the total payment amount for that stage.","format":"int32","type":"integer"},"transactionId":{"description":"This is the transaction identifier.","type":"string"}},"required":["discountedAmount","paidAmount","pointAmount","regTs","stepType","transactionAmount","transactionId"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/get-payment-status":{"post":{"description":"You can retrieve the payment status requested by the user.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through the error codes of the connected internal system as is. Treat undocumented `errorCode` as a failure and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"getPaymentStatus","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatusRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessPaymentStatusResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessPaymentStatusResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"Payment status information is returned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Check payment status","tags":["toss-pay"]}}}} ``` ## Refund payment > You can request a refund for a payment. Please check in advance whether refunds are possible and whether balance conditions are met.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through the error codes of the connected internal system as is. Treat undocumented \`errorCode\` as a failure and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"RefundPaymentRequest":{"description":"This is the request body for a Toss Pay refund.","properties":{"amount":{"description":"This is the amount to refund. If not provided, the full remaining amount of the payment to be refunded will be refunded. For partial refunds, be sure to use amount.","format":"int64","type":"integer"},"isTestPayment":{"description":"False for sandbox, true for live app. If true, a real payment is made.","type":"boolean"},"payToken":{"description":"This is the Toss Pay token. It is the token value of the payment to approve.","maxLength":30,"type":"string"},"reason":{"description":"This is the refund reason.","maxLength":55,"type":"string"}},"required":["isTestPayment","payToken"],"type":"object"},"TossApiSuccessRefundPaymentResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RefundPaymentResponse"}},"required":["resultType","success"],"type":"object"},"RefundPaymentResponse":{"description":"This is the response to a payment refund request.","properties":{"accountBankCode":{"description":"This is the bank code.","maxLength":3,"type":"string"},"accountBankName":{"description":"This is the bank name.","maxLength":20,"type":"string"},"accountNumber":{"description":"This is the account number. It includes partial masking.","maxLength":30,"type":"string"},"approvalTime":{"description":"This is the time the refund of the payment was processed. (yyyy-MM-dd HH:flag\\_mm:ss format)","type":"string"},"cardBinNumber":{"description":"This is the card BIN number. It is a value provided by the card issuer and may be masked.","maxLength":8,"type":"string"},"cardMethodType":{"description":"This is the card type. It is one of CREDIT (credit card) / CHECK (debit card) / PREPAYMENT (prepaid card).","maxLength":10,"type":"string"},"cardNum4Print":{"description":"The last 4 digits of the card selected by the user.","maxLength":4,"type":"string"},"cardNumber":{"description":"This is the masked card number.","maxLength":20,"type":"string"},"cardUserType":{"description":"This is the card user classification. It is one of PERSONAL (own card) / PERSONAL\\_FAMILY (family card) / CORP\\_PERSONAL (employee of a corporate-designated payment account) / CORP\\_PRIVATE (shared corporate card) / CORP\\_COMPANY (company for a corporate-designated payment account (Hana Card only)).","maxLength":20,"type":"string"},"cashReceiptMgtKey":{"description":"This is the identifier for the cash receipt management number.","maxLength":36,"type":"string"},"discountedAmount":{"description":"This is the discounted amount.","format":"int32","maxLength":7,"type":"integer"},"paidAmount":{"description":"This is the authorized amount for the payment method.","format":"int32","maxLength":7,"type":"integer"},"payToken":{"description":"This is the token of the refunded payment.","maxLength":30,"type":"string"},"refundNo":{"description":"This is the refund number.","type":"string"},"refundableAmount":{"description":"This is the refundable amount.","format":"int32","maxLength":7,"type":"integer"},"refundedAmount":{"description":"This is the refund request amount.","format":"int32","maxLength":7,"type":"integer"},"refundedDiscountAmount":{"description":"This is the discount amount actually deducted from the refund request amount.","format":"int32","maxLength":7,"type":"integer"},"refundedPaidAmount":{"description":"This is the payment-method amount actually deducted from the refund request amount.","format":"int32","maxLength":7,"type":"integer"},"transactionId":{"description":"This is the transaction ID.","maxLength":36,"type":"string"}},"required":["approvalTime","discountedAmount","paidAmount","payToken","refundNo","refundableAmount","refundedAmount","refundedDiscountAmount","refundedPaidAmount","transactionId"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/refund-payment":{"post":{"description":"You can request a refund for a payment. Please check in advance whether refunds are possible and whether balance conditions are met.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through the error codes of the connected internal system as is. Treat undocumented `errorCode` as a failure and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"refundPayment","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundPaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessRefundPaymentResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessRefundPaymentResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"The refund request was processed successfully."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Refund payment","tags":["toss-pay"]}}}} ``` ## Create a billing key > Generate a billing key for automatic payments.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through the error codes of the connected internal system as is. Treat undocumented \`errorCode\` as a failure and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"CreateBillingKeyRequest":{"description":"This is the request body for billing key creation.","properties":{"isTestPayment":{"description":"This is whether the payment is a test payment.","type":"boolean"},"productDesc":{"description":"This is the name of the automatic payment product.","type":"string"},"returnFailureUrl":{"description":"This is the URL to redirect to if authentication fails.","type":"string"},"returnSuccessUrl":{"description":"This is the URL to redirect to after successful authentication.","type":"string"}},"required":["isTestPayment","productDesc"]},"TossApiSuccessCreateBillingKeyResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/CreateBillingKeyResponse"}},"required":["resultType","success"],"type":"object"},"CreateBillingKeyResponse":{"description":"This is the billing key creation response.","properties":{"checkoutAndroidUri":{"description":"This is the Android authentication URI.","type":"string"},"checkoutIosUri":{"description":"This is the iOS authentication URI.","type":"string"},"checkoutUri":{"description":"This is the Toss app authentication URI.","type":"string"},"wrappedToken":{"description":"This is the wrapped billing key token.","type":"string"}},"required":["wrappedToken"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/create-billing-key":{"post":{"description":"Generate a billing key for automatic payments.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through the error codes of the connected internal system as is. Treat undocumented `errorCode` as a failure and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"createBillingKey","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBillingKeyRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessCreateBillingKeyResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessCreateBillingKeyResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"This is the result of request processing. Use the value of `resultType` to distinguish between success and failure."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Create a billing key","tags":["toss-pay"]}}}} ``` ## Check billing key status > Retrieve the current status of the billing key.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`5006\` | Cannot find the billing key. |\ > \| \`5005\` | This is an inactive billing key. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through error codes from the connected internal system as they are. Treat undocumented \`errorCode\` as failures and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"BillingKeyStatusRequest":{"description":"This is the request body for the billing key status lookup.","properties":{"isTestPayment":{"description":"This is whether the payment is a test payment.","type":"boolean"},"wrappedToken":{"description":"This is the wrapped billing key token.","type":"string"}},"required":["isTestPayment","wrappedToken"]},"TossApiSuccessBillingKeyStatusResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/BillingKeyStatusResponse"}},"required":["resultType","success"],"type":"object"},"BillingKeyStatusResponse":{"description":"This is the billing key status lookup response.","properties":{"accountBankCode":{"description":"This is the bank code. Returned only when the billing key is registered as an account.","type":"string"},"accountBankName":{"description":"This is the bank name. Returned only when the billing key is registered as an account.","type":"string"},"accountImgUrl":{"description":"This is the bank image URL. Returned only when the billing key is registered as an account.","type":"string"},"accountName":{"description":"This is the account holder name. Returned only when the billing key is registered as an account.","type":"string"},"accountNumber":{"description":"This is the account number. It is partially masked and returned only when the billing key is registered as an account.","type":"string"},"billingKeyStatus":{"description":"This is the billing key status used in the Apps in Toss Partner API.","enum":["CREATED","AUTHENTICATING","ACTIVE","REMOVED","CANCELED","FAILED","UNKNOWN"],"type":"string"},"cardCompanyName":{"description":"This is the card company name. Returned only when the billing key is registered as a card.","type":"string"},"cardCompanyNo":{"description":"This is the card company code. Returned only when the billing key is registered as a card.","format":"int32","type":"integer"},"cardImgUrl":{"description":"This is the card image URL. Returned only when the billing key is registered as a card.","type":"string"},"cardName":{"description":"This is the card name. Returned only when the billing key is registered as a card.","type":"string"},"cardNumber":{"description":"This is the masked card number. Returned only when the billing key is registered as a card.","type":"string"}},"required":["billingKeyStatus"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/get-billing-key-status":{"post":{"description":"Retrieve the current status of the billing key.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `5006` | Cannot find the billing key. |\n| `5005` | This is an inactive billing key. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through error codes from the connected internal system as they are. Treat undocumented `errorCode` as failures and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"getBillingKeyStatus","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingKeyStatusRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessBillingKeyStatusResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessBillingKeyStatusResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"This is the result of request processing. Use the value of `resultType` to distinguish between success and failure."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Check billing key status","tags":["toss-pay"]}}}} ``` ## Approve automatic payments > Approve the payment using the billing key.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`5006\` | Cannot find the billing key. |\ > \| \`5005\` | This is an inactive billing key. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through error codes from the connected internal system as they are. Treat undocumented \`errorCode\` as failures and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"ExecuteBillingRequest":{"description":"This is the request body for automatic payment approval.","properties":{"amount":{"description":"This is the payment amount.","format":"int64","type":"integer"},"amountServiceFee":{"description":"This is the service fee.","format":"int64","type":"integer"},"amountTaxFree":{"description":"This is the tax-exempt amount.","format":"int64","type":"integer"},"amountTaxable":{"description":"This is the taxable amount.","format":"int64","type":"integer"},"amountVat":{"description":"This is the VAT.","format":"int64","type":"integer"},"cashReceipt":{"description":"Whether to issue a cash receipt. If omitted, it is treated as true.","type":"boolean"},"cashReceiptTradeOption":{"description":"This is the cash receipt issuance type. It is one of GENERAL/CULTURE/PUBLIC\\_TP, and if omitted it is treated as GENERAL.","type":"string"},"isTestPayment":{"description":"This is whether the payment is a test payment.","type":"boolean"},"orderNo":{"description":"This is the order number.","type":"string"},"productDesc":{"description":"This is the product description.","type":"string"},"sendFailPush":{"description":"Whether to send a push notification if payment fails. If omitted, it is treated as true.","type":"boolean"},"spreadOut":{"description":"This is the number of installment months. If 0, it is a one-time payment.","format":"int32","type":"integer"},"wrappedToken":{"description":"This is the wrapped billing key token.","type":"string"}},"required":["amount","amountTaxFree","isTestPayment","orderNo","productDesc","spreadOut","wrappedToken"]},"TossApiSuccessExecuteBillingResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/ExecuteBillingResponse"}},"required":["resultType","success"],"type":"object"},"ExecuteBillingResponse":{"description":"This is the automatic payment approval response.","properties":{"accountBankCode":{"description":"This is the bank code. Returned only when the payment is made with Toss Money (account).","type":"string"},"accountBankName":{"description":"This is the bank name. Returned only when the payment is made with Toss Money (account).","type":"string"},"accountNumber":{"description":"This is the account number. It is partially masked and returned only when the payment is made with Toss Money (account).","type":"string"},"amount":{"description":"This is the total payment amount.","format":"int64","type":"integer"},"approvalTime":{"description":"This is the time when the automatic payment was approved. (yyyy-MM-dd HH:flag\\_mm:ss format)","type":"string"},"cardAuthorizationNo":{"description":"This is the card approval number. Returned only for card payments.","type":"string"},"cardBinNumber":{"description":"This is the card BIN number. This value is provided by the card company, may be masked, and is returned only for card payments.","type":"string"},"cardCompanyCode":{"description":"This is the card company code. Returned only for card payments.","format":"int32","type":"integer"},"cardCompanyName":{"description":"This is the card company name. Returned only for card payments.","type":"string"},"cardMethodType":{"description":"This is the card type. It is one of CREDIT (credit card)/CHECK (debit card)/PREPAYMENT (prepaid card), and is returned only for card payments.","type":"string"},"cardNum4Print":{"description":"The last 4 digits of the card selected by the user. Returned only for card payments.","type":"string"},"cardNumber":{"description":"This is the masked card number. Returned only for card payments.","type":"string"},"cardUserType":{"description":"This is the card user type. It is one of PERSONAL (self-owned card)/PERSONAL\\_FAMILY (family card)/CORP\\_PERSONAL (employees of a corporate-designated payment account)/CORP\\_PRIVATE (corporate shared)/CORP\\_COMPANY (company of a corporate-designated payment account, Hana Card only), and is returned only for card payments.","type":"string"},"cashReceiptMgtKey":{"description":"This is the identifier for the cash receipt management number. Returned only when the payment is made with Toss Money (account).","type":"string"},"code":{"description":"This is the result code of the automatic payment approval processing. 0 for success, -1 for failure.","format":"int32","type":"integer"},"discountedAmount":{"description":"This is the payment amount after discounts are applied.","format":"int64","type":"integer"},"errorCode":{"description":"This is the error code returned when automatic payment fails. It is returned when code is -1.","type":"string"},"mode":{"description":"Indicates the environment in which the payment was processed. One of NORMAL or TEST.","type":"string"},"msg":{"description":"This is the message containing the reason for failure when automatic payment fails. It is returned when code is -1.","type":"string"},"noInterest":{"description":"This indicates whether it is interest-free installments. Returned only for card payments.","type":"boolean"},"orderNo":{"description":"This is the requested order number.","type":"string"},"paidAmount":{"description":"This is the amount actually approved through the payment method.","format":"int64","type":"integer"},"payMethod":{"description":"This is the payment method. It takes CARD or TOSS\\_MONEY.","type":"string"},"payToken":{"description":"This is the token that identifies this automatic payment.","type":"string"},"salesCheckLinkUrl":{"description":"This is the sales slip confirmation URL. Returned only for card payments.","type":"string"},"spreadOut":{"description":"This is the number of installment months. If 0, it is a one-time payment, and is returned only for card payments.","format":"int32","type":"integer"},"transactionId":{"description":"This is the transaction ID that identifies the transaction.","type":"string"}},"required":["code"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/execute-billing":{"post":{"description":"Approve the payment using the billing key.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `5006` | Cannot find the billing key. |\n| `5005` | This is an inactive billing key. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through error codes from the connected internal system as they are. Treat undocumented `errorCode` as failures and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"executeBilling","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteBillingRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessExecuteBillingResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessExecuteBillingResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"This is the result of request processing. Use the value of `resultType` to distinguish between success and failure."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Approve automatic payments","tags":["toss-pay"]}}}} ``` ## Refund automatic payment > Refund a payment approved for automatic payment.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through the error codes of the connected internal system as is. Treat undocumented \`errorCode\` as a failure and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"RefundBillingRequest":{"description":"This is the request body for an automatic payment refund.","properties":{"isTestPayment":{"description":"This is whether the payment is a test payment.","type":"boolean"},"payToken":{"description":"This is the Toss Pay token for the automatic payment to be refunded.","type":"string"},"reason":{"description":"This is the refund reason.","type":"string"}},"required":["isTestPayment","payToken"]},"TossApiSuccessRefundBillingResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RefundBillingResponse"}},"required":["resultType","success"],"type":"object"},"RefundBillingResponse":{"description":"This is the automatic payment refund response.","properties":{"accountBankCode":{"description":"This is the bank code.","type":"string"},"accountBankName":{"description":"This is the bank name.","type":"string"},"accountNumber":{"description":"This is the account number. It is partially masked.","type":"string"},"approvalTime":{"description":"This is the time the refund was processed. (yyyy-MM-dd HH:flag\\_mm:ss format)","type":"string"},"cardBinNumber":{"description":"This is the card BIN number. It is a value provided by the card issuer and may be masked.","type":"string"},"cardMethodType":{"description":"This is the card type. It is one of CREDIT (credit card) / CHECK (debit card) / PREPAYMENT (prepaid card).","type":"string"},"cardNum4Print":{"description":"The last 4 digits of the card selected by the user.","type":"string"},"cardNumber":{"description":"This is the masked card number.","type":"string"},"cardUserType":{"description":"This is the card user classification. It is one of PERSONAL (own card) / PERSONAL\\_FAMILY (family card) / CORP\\_PERSONAL (employee of a corporate-designated payment account) / CORP\\_PRIVATE (shared corporate card) / CORP\\_COMPANY (company for a corporate-designated payment account (Hana Card only)).","type":"string"},"cashReceiptMgtKey":{"description":"This is the identifier for the cash receipt management number.","type":"string"},"discountedAmount":{"description":"This is the discounted amount.","format":"int32","type":"integer"},"paidAmount":{"description":"This is the authorized amount for the payment method.","format":"int32","type":"integer"},"payToken":{"description":"This is the token of the refunded payment.","type":"string"},"refundNo":{"description":"This is the refund number.","type":"string"},"refundableAmount":{"description":"This is the refundable amount.","format":"int32","type":"integer"},"refundedAmount":{"description":"This is the refund request amount.","format":"int32","type":"integer"},"refundedDiscountAmount":{"description":"This is the discount amount actually deducted from the refund request amount.","format":"int32","type":"integer"},"refundedPaidAmount":{"description":"This is the payment-method amount actually deducted from the refund request amount.","format":"int32","type":"integer"},"transactionId":{"description":"This is the transaction ID.","type":"string"}},"required":["approvalTime","discountedAmount","paidAmount","payToken","refundNo","refundableAmount","refundedAmount","refundedDiscountAmount","refundedPaidAmount","transactionId"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/refund-billing":{"post":{"description":"Refund a payment approved for automatic payment.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through the error codes of the connected internal system as is. Treat undocumented `errorCode` as a failure and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"refundBilling","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundBillingRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessRefundBillingResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessRefundBillingResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"This is the result of request processing. Use the value of `resultType` to distinguish between success and failure."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Refund automatic payment","tags":["toss-pay"]}}}} ``` ## Delete billing key > Delete (cancel) the billing key.\ > \ > \### Business error code\ > \ > The errors below respond with HTTP 200 and \`resultType: FAIL\`.\ > \ > \| errorCode | Description |\ > \| --------- | ------------------------------------------------------------ |\ > \| \`5001\` | You are not subscribed to Toss Pay. |\ > \| \`5006\` | Cannot find the billing key. |\ > \| \`4010\` | Authentication information cannot be found. |\ > \| \`4095\` | The request limit has been exceeded. Please try again later. |\ > \ > This API can pass through error codes from the linked internal system as-is. Treat undocumented \`errorCode\` as failures and refer to the \`reason\` message.\ > \ > \*\*Request limit\*\*: 3,000 per minute per app ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss partner API","version":"1.0.0"},"tags":[{"description":"This is an API that processes requests related to Toss Pay.","name":"toss-pay"}],"servers":[{"description":"Operations (simple login, message sending, Toss points payouts, etc.)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the [Use the server API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/integration/server-api) document for how to issue and manage certificates.","type":"mutualTLS"}},"schemas":{"RemoveBillingKeyRequest":{"description":"This is the request body for deleting a billing key .","properties":{"isTestPayment":{"description":"This is whether the payment is a test payment.","type":"boolean"},"wrappedToken":{"description":"This is the wrapped billing key token.","type":"string"}},"required":["isTestPayment","wrappedToken"]},"TossApiSuccessRemoveBillingKeyResponse":{"description":"This is the success response envelope.","properties":{"resultType":{"description":"This is the processing result. If successful, it is `SUCCESS`.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RemoveBillingKeyResponse"}},"required":["resultType","success"],"type":"object"},"RemoveBillingKeyResponse":{"description":"This is the response for deleting a billing key .","properties":{"code":{"description":"This is the result code for billing key deletion. It is 0 on success.","format":"int32","type":"integer"},"msg":{"description":"This is the message containing the failure reason when billing key deletion fails.","type":"string"}},"required":["code"]},"TossApiFail":{"description":"This is the failure response envelope. Business errors are returned with HTTP 200, so be sure to check `resultType`.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"This is the response when request field validation fails.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"This is the processing result. Treat any value other than `SUCCESS` as a failure. It is usually `FAIL`.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"It is always null on failure."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"This is detailed error information.","properties":{"data":{"description":"This is additional error information. When the request limit is exceeded, `retryAfterSeconds` is included.","properties":{"errorDetails":{"description":"This is a detailed list of field-by-field validation failures.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"This is the error code. Refer to each API's business error code table.","type":"string"},"errorType":{"description":"This is the internal error classification value. Use `errorCode` for error categorization.","format":"int32","type":"integer"},"reason":{"description":"This is a human-readable error description.","type":"string"},"title":{"description":"This is the error title. It is usually null.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"This is a detailed list of field-by-field validation failures.","properties":{"field":{"description":"This is the name of the field that failed validation.","type":"string"},"message":{"description":"This is the reason for validation failure.","type":"string"},"rejectedValue":{"description":"This is the rejected input value."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/remove-billing-key":{"post":{"description":"Delete (cancel) the billing key.\n\n### Business error code\n\nThe errors below respond with HTTP 200 and `resultType: FAIL`.\n\n| errorCode | Description |\n| --------- | ------------------------------------------------------------ |\n| `5001` | You are not subscribed to Toss Pay. |\n| `5006` | Cannot find the billing key. |\n| `4010` | Authentication information cannot be found. |\n| `4095` | The request limit has been exceeded. Please try again later. |\n\nThis API can pass through error codes from the linked internal system as-is. Treat undocumented `errorCode` as failures and refer to the `reason` message.\n\n**Request limit**: 3,000 per minute per app","operationId":"removeBillingKey","parameters":[{"description":"It's a key for authenticating users. It can be obtained through the [Get user information](https://developers-apps-in-toss.toss.im/api/en/toss-login#get-api-partner-v1-apps-in-toss-user-oauth2-login-me) API","in":"header","name":"x-toss-user-key","required":false,"schema":{"type":"string"}},{"description":"It's a key for authenticating users. You can issue it with the [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/user/user.getanonymouskey) function in the mini app SDK","in":"header","name":"x-anon-key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveBillingKeyRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessRemoveBillingKeyResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessRemoveBillingKeyResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"This is the result of request processing. Use the value of `resultType` to distinguish between success and failure."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"The request body is not in the correct format. Check the field-by-field details in `error.data.errorDetails`."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"This is an unclassified server error. If it keeps failing, please contact the partner support channel."}},"summary":"Delete billing key","tags":["toss-pay"]}}}} ``` --- # 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/api/en/toss-pay.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.