Toss Pay

Create a payment

post

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

Authorizations

mutualTLS

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 document for how to issue and manage certificates.

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for creating a Toss Pay payment.

amountinteger · int64 · max: 7Required

This is the total payment amount.

Example: 1000

amountServiceFeeinteger · int64 · max: 7Optional

This is the service charge amount within the payment amount.

Example: 0

amountTaxFreeinteger · int64 · max: 7Required

This is the tax-exempt amount within the payment amount. If it is a taxable product, send 0.

Example: 0

amountTaxableinteger · int64 · max: 7Optional

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.

Example: 909

amountVatinteger · int64 · max: 7Optional

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.

Example: 91

cashReceiptbooleanOptional

This indicates whether a cash receipt can be issued. If null, it will not be issued.

Example: false

cashReceiptTradeOptionstring · max: 10Optional

This is the cash receipt issuance type. It is one of CULTURE (culture expenses) / GENERAL (general, default) / PUBLIC_TP (transportation expenses).

Example: GENERAL

enablePayMethodsstring · max: 100Optional

These are the available payment methods. You can use TOSS_MONEY/CARD or null.

Example: CARD

installmentstring · max: 10Optional

This is the installment restriction type. It is one of USE (use installments, default) / NOT_USE (do not use installments).

Example: USE

isTestPaymentbooleanRequired

False for sandbox, true for live app. If true, a real payment is made.

Example: false

orderNostring · max: 50Required

This is the merchant's product order number. You can use numbers, letters, and special characters (_-:.^@).

Example: 20250422-01

productDescstring · max: 255Required

This is the product description. Please be careful with encoding if it includes Korean characters.

Example: 테스트결제

Responses

200

The payment creation request was processed successfully.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/make-payment

POST /api-partner/v1/apps-in-toss/pay/make-payment HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "orderNo": "20250422-01",
  "productDesc": "테스트결제",
  "amount": 1000,
  "amountTaxFree": 0,
  "amountTaxable": 909,
  "amountVat": 91,
  "amountServiceFee": 0,
  "enablePayMethods": "CARD",
  "cashReceipt": false,
  "cashReceiptTradeOption": "GENERAL",
  "installment": "USE",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "payToken": "pay_9f3ac72e8d41b0"
  }
}

Execute payment

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for an approved payment that has been user-authenticated.

isTestPaymentbooleanRequired

False for sandbox, true for live app. If true, a real payment is made.

Example: false

orderNostring · max: 50Optional

This is the merchant's product order number. You can use numbers, letters, and special characters (_-:.^@).

Example: 20250422-01

payTokenstring · max: 30Required

This is the Toss Pay token. It is the token value of the payment to approve.

Example: pay_9f3ac72e8d41b0

Responses

200

The payment approval request was processed successfully.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/execute-payment

POST /api-partner/v1/apps-in-toss/pay/execute-payment HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "payToken": "pay_9f3ac72e8d41b0",
  "orderNo": "20250422-01",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "accountBankCode": "88",
    "accountBankName": "신한은행",
    "accountNumber": "5678********",
    "amount": 15000,
    "approvalTime": "2025-04-22 13:12:00",
    "cardAuthorizationNo": "A123456789",
    "cardBinNumber": "123456",
    "cardCompanyCode": 25,
    "cardCompanyName": "현대카드",
    "cardMethodType": "CREDIT",
    "cardNum4Print": "1234",
    "cardNumber": "654321******1234",
    "cardUserType": "PERSONAL",
    "cashReceiptMgtKey": "abc123",
    "code": 0,
    "discountedAmount": 12000,
    "errorCode": "INSUFFICIENT_BALANCE",
    "mode": "NORMAL",
    "msg": "잔액이 부족합니다.",
    "noInterest": false,
    "orderNo": "20250422-01",
    "paidAmount": 12000,
    "payMethod": "CARD",
    "payToken": "pay_9f3ac72e8d41b0",
    "salesCheckLinkUrl": "https://pay.toss.im/receipt/abc123",
    "spreadOut": 3,
    "stateMsg": "정상처리",
    "transactionId": "txn_7f3a9c2e81b4"
  }
}

Check payment status

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

These are the request parameters for payment status inquiry.

isTestPaymentbooleanRequired

Indicates whether this is a test payment.

Example: false

orderNostringOptional

This is the order number. When making the request, either this value or payToken is required.

Example: ORDER_20250407

payTokenstringOptional

This is the key that identifies the payment. When making the request, either this value or orderNo is required.

Example: pay_9f3ac72e8d41b0

Responses

200

Payment status information is returned.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/get-payment-status

POST /api-partner/v1/apps-in-toss/pay/get-payment-status HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "payToken": "pay_9f3ac72e8d41b0",
  "orderNo": "ORDER_20250407",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "accountBankCode": "88",
    "accountBankName": "신한은행",
    "accountNumber": "5678********",
    "amount": 15000,
    "amountServiceFee": 0,
    "amountTaxFree": 0,
    "amountTaxable": 10000,
    "amountVat": 1000,
    "card": {
      "cardAuthorizationNo": "A123456789",
      "cardBinNumber": "123456",
      "cardCompanyCode": 25,
      "cardCompanyName": "현대카드",
      "cardMethodType": "SINGLE",
      "cardNum4Print": "1234",
      "cardNumber": "654321******1234",
      "cardUserType": "PERSONAL",
      "noInterest": false,
      "salesCheckLinkUrl": "https://pay.toss.im/receipt/abc123",
      "spreadOut": 3
    },
    "createdTs": "2025-04-07T13:12:00Z",
    "discountAmountV2": 3000,
    "discountedAmount": 12000,
    "disposableCupDeposit": 500,
    "mode": "NORMAL",
    "orderNo": "ORDER_20250407",
    "paidAmount": 10000,
    "paidPointV2": 2000,
    "paidTs": "2025-04-07T13:12:05Z",
    "payMethod": "CARD",
    "payStatus": "DONE",
    "payToken": "pay_9f3ac72e8d41b0",
    "refundableAmount": 8000,
    "transactions": []
  }
}

Refund payment

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for a Toss Pay refund.

amountinteger · int64Optional

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.

Example: 1000

isTestPaymentbooleanRequired

False for sandbox, true for live app. If true, a real payment is made.

Example: false

payTokenstring · max: 30Required

This is the Toss Pay token. It is the token value of the payment to approve.

Example: pay_9f3ac72e8d41b0

reasonstring · max: 55Optional

This is the refund reason.

Example: 고객 단순 변심

Responses

200

The refund request was processed successfully.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/refund-payment

POST /api-partner/v1/apps-in-toss/pay/refund-payment HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "payToken": "pay_9f3ac72e8d41b0",
  "amount": 1000,
  "reason": "고객 단순 변심",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "accountBankCode": "88",
    "accountBankName": "신한은행",
    "accountNumber": "5678********",
    "approvalTime": "2025-04-22 13:15:00",
    "cardBinNumber": "123456",
    "cardMethodType": "CREDIT",
    "cardNum4Print": "1234",
    "cardNumber": "654321******1234",
    "cardUserType": "PERSONAL",
    "cashReceiptMgtKey": "abc123",
    "discountedAmount": 0,
    "paidAmount": 1000,
    "payToken": "pay_9f3ac72e8d41b0",
    "refundNo": "20250422-01-R1",
    "refundableAmount": 0,
    "refundedAmount": 1000,
    "refundedDiscountAmount": 0,
    "refundedPaidAmount": 1000,
    "transactionId": "txn_7f3a9c2e81b4"
  }
}

Create a billing key

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for billing key creation.

isTestPaymentbooleanRequired

This is whether the payment is a test payment.

Example: false

productDescstringRequired

This is the name of the automatic payment product.

Example: 월간 구독

returnFailureUrlstringOptional

This is the URL to redirect to if authentication fails.

Example: https://example-partner.com/billing/failure

returnSuccessUrlstringOptional

This is the URL to redirect to after successful authentication.

Example: https://example-partner.com/billing/success

Responses

200

This is the result of request processing. Use the value of resultType to distinguish between success and failure.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/create-billing-key

POST /api-partner/v1/apps-in-toss/pay/create-billing-key HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "productDesc": "월간 구독",
  "returnSuccessUrl": "https://example-partner.com/billing/success",
  "returnFailureUrl": "https://example-partner.com/billing/failure",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "checkoutAndroidUri": "intent://billing/checkout#Intent;package=viva.republica.toss;end",
    "checkoutIosUri": "supertoss://billing/checkout?token=3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "checkoutUri": "supertoss://billing/checkout?token=3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Check billing key status

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for the billing key status lookup.

isTestPaymentbooleanRequired

This is whether the payment is a test payment.

Example: false

wrappedTokenstringRequired

This is the wrapped billing key token.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

200

This is the result of request processing. Use the value of resultType to distinguish between success and failure.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/get-billing-key-status

POST /api-partner/v1/apps-in-toss/pay/get-billing-key-status HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "accountBankCode": "88",
    "accountBankName": "신한은행",
    "accountImgUrl": "https://pay.toss.im/img/bank.png",
    "accountName": "홍길동",
    "accountNumber": "5678********",
    "billingKeyStatus": "ACTIVE",
    "cardCompanyName": "현대카드",
    "cardCompanyNo": 25,
    "cardImgUrl": "https://pay.toss.im/img/card.png",
    "cardName": "현대카드 the Green",
    "cardNumber": "654321******1234"
  }
}

Approve automatic payments

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for automatic payment approval.

amountinteger · int64Required

This is the payment amount.

Example: 1000

amountServiceFeeinteger · int64Optional

This is the service fee.

Example: 0

amountTaxFreeinteger · int64Required

This is the tax-exempt amount.

Example: 0

amountTaxableinteger · int64Optional

This is the taxable amount.

Example: 909

amountVatinteger · int64Optional

This is the VAT.

Example: 91

cashReceiptbooleanOptional

Whether to issue a cash receipt. If omitted, it is treated as true.

Example: true

cashReceiptTradeOptionstringOptional

This is the cash receipt issuance type. It is one of GENERAL/CULTURE/PUBLIC_TP, and if omitted it is treated as GENERAL.

Example: GENERAL

isTestPaymentbooleanRequired

This is whether the payment is a test payment.

Example: false

orderNostringRequired

This is the order number.

Example: ORDER-20260408-001

productDescstringRequired

This is the product description.

Example: 월간 구독 결제

sendFailPushbooleanOptional

Whether to send a push notification if payment fails. If omitted, it is treated as true.

Example: true

spreadOutinteger · int32Required

This is the number of installment months. If 0, it is a one-time payment.

Example: 0

wrappedTokenstringRequired

This is the wrapped billing key token.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

200

This is the result of request processing. Use the value of resultType to distinguish between success and failure.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/execute-billing

POST /api-partner/v1/apps-in-toss/pay/execute-billing HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orderNo": "ORDER-20260408-001",
  "productDesc": "월간 구독 결제",
  "spreadOut": 0,
  "amount": 1000,
  "amountTaxFree": 0,
  "amountTaxable": 909,
  "amountVat": 91,
  "amountServiceFee": 0,
  "cashReceipt": true,
  "sendFailPush": true,
  "cashReceiptTradeOption": "GENERAL",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "accountBankCode": "88",
    "accountBankName": "신한은행",
    "accountNumber": "5678********",
    "amount": 50000,
    "approvalTime": "2026-05-21 10:00:00",
    "cardAuthorizationNo": "A123456789",
    "cardBinNumber": "123456",
    "cardCompanyCode": 25,
    "cardCompanyName": "현대카드",
    "cardMethodType": "CREDIT",
    "cardNum4Print": "1234",
    "cardNumber": "654321******1234",
    "cardUserType": "PERSONAL",
    "cashReceiptMgtKey": "abc123",
    "code": 0,
    "discountedAmount": 45000,
    "errorCode": "COMMON_BILLING_KEY_NOT_FOUND",
    "mode": "NORMAL",
    "msg": "등록된 빌링키를 찾을 수 없어요.",
    "noInterest": false,
    "orderNo": "ORDER-20260408-001",
    "paidAmount": 45000,
    "payMethod": "CARD",
    "payToken": "pay_9f3ac72e8d41b0",
    "salesCheckLinkUrl": "https://pay.toss.im/receipt/abc123",
    "spreadOut": 0,
    "transactionId": "txn_7f3a9c2e81b4"
  }
}

Refund automatic payment

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for an automatic payment refund.

isTestPaymentbooleanRequired

This is whether the payment is a test payment.

Example: false

payTokenstringRequired

This is the Toss Pay token for the automatic payment to be refunded.

Example: pay_9f3ac72e8d41b0

reasonstringOptional

This is the refund reason.

Example: 고객 단순 변심

Responses

200

This is the result of request processing. Use the value of resultType to distinguish between success and failure.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/refund-billing

POST /api-partner/v1/apps-in-toss/pay/refund-billing HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "payToken": "pay_9f3ac72e8d41b0",
  "reason": "고객 단순 변심",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "accountBankCode": "88",
    "accountBankName": "신한은행",
    "accountNumber": "5678********",
    "approvalTime": "2026-05-21 10:00:00",
    "cardBinNumber": "123456",
    "cardMethodType": "CREDIT",
    "cardNum4Print": "1234",
    "cardNumber": "654321******1234",
    "cardUserType": "PERSONAL",
    "cashReceiptMgtKey": "abc123",
    "discountedAmount": 2000,
    "paidAmount": 10000,
    "payToken": "pay_9f3ac72e8d41b0",
    "refundNo": "20250422-01-R1",
    "refundableAmount": 8000,
    "refundedAmount": 5000,
    "refundedDiscountAmount": 1000,
    "refundedPaidAmount": 4000,
    "transactionId": "txn_7f3a9c2e81b4"
  }
}

Delete billing key

post

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

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is the request body for deleting a billing key .

isTestPaymentbooleanRequired

This is whether the payment is a test payment.

Example: false

wrappedTokenstringRequired

This is the wrapped billing key token.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

200

This is the result of request processing. Use the value of resultType to distinguish between success and failure.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/pay/remove-billing-key

POST /api-partner/v1/apps-in-toss/pay/remove-billing-key HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isTestPayment": false
}

{
  "resultType": "SUCCESS",
  "success": {
    "code": 0,
    "msg": "등록된 빌링키를 찾을 수 없어요."
  }
}

PreviousIn-app payment

NextPush, notifications

Was this helpful?