Toss Pay

创建支付

post

创建支付。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是用于生成 Toss Pay 支付的请求正文。

amountinteger · int64 · 最大值: 7必填

这是总支付金额。

Example: 1000

amountServiceFeeinteger · int64 · 最大值: 7可选

这是支付金额中的服务费。

Example: 0

amountTaxFreeinteger · int64 · 最大值: 7必填

这是支付金额中的免税金额。如果是应税商品，请发送 0。

Example: 0

amountTaxableinteger · int64 · 最大值: 7可选

这是支付金额中的应税金额。如果未单独设置应税金额，而将免税金额发送为 0 元，Toss Pay 服务器会自动计算应税金额和增值税。

Example: 909

amountVatinteger · int64 · 最大值: 7可选

这是支付金额中的增值税。如果没有值，则在将要退款的应税金额除以 11 后，按小数点第一位进行进位计算。

Example: 91

cashReceiptboolean可选

这是是否可以开具现金收据。为 null 时不会开具。

Example: false

cashReceiptTradeOptionstring · 最大值: 10可选

这是现金收据开具类型。是 CULTURE（文化费用）/GENERAL（普通，默认值）/PUBLIC_TP（交通费）之一。

Example: GENERAL

enablePayMethodsstring · 最大值: 100可选

这是可用的支付方式。可以使用 TOSS_MONEY/CARD 或 null 值。

Example: CARD

installmentstring · 最大值: 10可选

这是分期限制类型。是 USE（使用分期，默认值）/NOT_USE（不使用分期）之一。

Example: USE

isTestPaymentboolean必填

沙盒环境为 false，正式应用为 true。为 true 时会发生真实支付。

Example: false

orderNostring · 最大值: 50必填

这是商家的商品订单号。可以使用数字、英文字母和特殊字符（_-:.^@）。

Example: 20250422-01

productDescstring · 最大值: 255必填

这是商品说明。如果包含韩文，请注意编码。

Example: 테스트결제

响应

200

支付创建请求已成功处理。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

执行支付

post

请求批准已完成支付认证的支付单。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是针对已完成用户认证的支付的批准请求正文。

isTestPaymentboolean必填

沙盒环境为 false，正式应用为 true。为 true 时会发生真实支付。

Example: false

orderNostring · 最大值: 50可选

这是商家的商品订单号。可以使用数字、英文字母和特殊字符（_-:.^@）。

Example: 20250422-01

payTokenstring · 最大值: 30必填

这是 Toss Pay 令牌。它是要批准的支付订单的令牌值。

Example: pay_9f3ac72e8d41b0

响应

200

支付批准请求已成功处理。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

查询支付状态

post

可以查询用户请求的支付状态。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是支付状态查询请求参数。

isTestPaymentboolean必填

表示是否为测试支付。

Example: false

orderNostring可选

这是订单号。请求时，这个值和 payToken 二者之一为必填。

Example: ORDER_20250407

payTokenstring可选

这是用于识别支付的键。请求时，这个值和 orderNo 二者之一为必填。

Example: pay_9f3ac72e8d41b0

响应

200

返回支付状态信息。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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": []
  }
}

支付退款

post

可以对支付单发起退款。请提前确认可退款与余额条件等。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是用于 Toss Pay 退款的请求正文。

amountinteger · int64可选

这是要退款的金额。未填写时，将退款到该支付单剩余的全部金额。部分退款时请务必使用 amount。

Example: 1000

isTestPaymentboolean必填

沙盒环境为 false，正式应用为 true。为 true 时会发生真实支付。

Example: false

payTokenstring · 最大值: 30必填

这是 Toss Pay 令牌。它是要批准的支付订单的令牌值。

Example: pay_9f3ac72e8d41b0

reasonstring · 最大值: 55可选

这是退款原因。

Example: 고객 단순 변심

响应

200

退款请求已成功处理。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

创建计费密钥

post

自动支付用的计费密钥。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是创建计费密钥的请求正文。

isTestPaymentboolean必填

是否为测试支付。

Example: false

productDescstring必填

这是自动扣款商品名称。

Example: 월간 구독

returnFailureUrlstring可选

这是认证失败时要跳转的 URL。

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

returnSuccessUrlstring可选

这是认证成功后要跳转的 URL。

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

响应

200

这是请求处理结果。请根据 resultType 值区分成功/失败。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

查询计费密钥状态

post

查询计费密钥的当前状态。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

5006

找不到计费密钥。

5005

这是已停用的计费密钥。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

这个 API 可以原样传递已联动内部系统的错误代码。未文档化的 errorCode 视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是查询计费密钥状态的请求正文。

isTestPaymentboolean必填

是否为测试支付。

Example: false

wrappedTokenstring必填

这是包装后的计费密钥令牌。

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

响应

200

这是请求处理结果。请根据 resultType 值区分成功/失败。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

批准自动支付

post

使用计费密钥来批准支付。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

5006

找不到计费密钥。

5005

这是已停用的计费密钥。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

这个 API 可以原样传递已联动内部系统的错误代码。未文档化的 errorCode 视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是自动扣款批准请求正文。

amountinteger · int64必填

这是支付金额。

Example: 1000

amountServiceFeeinteger · int64可选

这是服务费。

Example: 0

amountTaxFreeinteger · int64必填

这是免税金额。

Example: 0

amountTaxableinteger · int64可选

这是应税金额。

Example: 909

amountVatinteger · int64可选

这是增值税。

Example: 91

cashReceiptboolean可选

这是是否开具现金收据。若无值则按 true 处理。

Example: true

cashReceiptTradeOptionstring可选

这是现金收据开具类型。可为 GENERAL/CULTURE/PUBLIC_TP 之一，若无值则按 GENERAL 处理。

Example: GENERAL

isTestPaymentboolean必填

是否为测试支付。

Example: false

orderNostring必填

这是订单号。

Example: ORDER-20260408-001

productDescstring必填

这是商品说明。

Example: 월간 구독 결제

sendFailPushboolean可选

这是支付失败时是否发送推送。若无值则按 true 处理。

Example: true

spreadOutinteger · int32必填

这是分期期数。0 表示一次性付款。

Example: 0

wrappedTokenstring必填

这是包装后的计费密钥令牌。

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

响应

200

这是请求处理结果。请根据 resultType 值区分成功/失败。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

自动支付退款

post

对已通过自动支付批准的支付单进行退款。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是自动支付退款请求正文。

isTestPaymentboolean必填

是否为测试支付。

Example: false

payTokenstring必填

这是要退款的自动支付对应的 Toss Pay 令牌。

Example: pay_9f3ac72e8d41b0

reasonstring可选

这是退款原因。

Example: 고객 단순 변심

响应

200

这是请求处理结果。请根据 resultType 值区分成功/失败。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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"
  }
}

删除计费密钥

post

删除（解除）计费密钥。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5001

尚未签约 Toss Pay。

5006

找不到计费密钥。

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是计费密钥删除请求正文。

isTestPaymentboolean必填

是否为测试支付。

Example: false

wrappedTokenstring必填

这是包装后的计费密钥令牌。

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

响应

200

这是请求处理结果。请根据 resultType 值区分成功/失败。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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": "등록된 빌링키를 찾을 수 없어요."
  }
}

上一页应用内支付

下一页推送、通知

这有帮助吗？