> 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/zh/toss-pay.md). # Toss Pay ## 创建支付 > 创建支付。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"MakePaymentRequest":{"description":"这是用于生成 Toss Pay 支付的请求正文。","properties":{"amount":{"description":"这是总支付金额。","format":"int64","maxLength":7,"type":"integer"},"amountServiceFee":{"description":"这是支付金额中的服务费。","format":"int64","maxLength":7,"type":"integer"},"amountTaxFree":{"description":"这是支付金额中的免税金额。如果是应税商品，请发送 0。","format":"int64","maxLength":7,"type":"integer"},"amountTaxable":{"description":"这是支付金额中的应税金额。如果未单独设置应税金额，而将免税金额发送为 0 元，Toss Pay 服务器会自动计算应税金额和增值税。","format":"int64","maxLength":7,"type":"integer"},"amountVat":{"description":"这是支付金额中的增值税。如果没有值，则在将要退款的应税金额除以 11 后，按小数点第一位进行进位计算。","format":"int64","maxLength":7,"type":"integer"},"cashReceipt":{"description":"这是是否可以开具现金收据。为 null 时不会开具。","type":"boolean"},"cashReceiptTradeOption":{"description":"这是现金收据开具类型。是 CULTURE（文化费用）/GENERAL（普通，默认值）/PUBLIC\\_TP（交通费）之一。","maxLength":10,"type":"string"},"enablePayMethods":{"description":"这是可用的支付方式。可以使用 TOSS\\_MONEY/CARD 或 null 值。","maxLength":100,"type":"string"},"installment":{"description":"这是分期限制类型。是 USE（使用分期，默认值）/NOT\\_USE（不使用分期）之一。","maxLength":10,"type":"string"},"isTestPayment":{"description":"沙盒环境为 false，正式应用为 true。为 true 时会发生真实支付。","type":"boolean"},"orderNo":{"description":"这是商家的商品订单号。可以使用数字、英文字母和特殊字符（\\_-:.^@）。","maxLength":50,"type":"string"},"productDesc":{"description":"这是商品说明。如果包含韩文，请注意编码。","maxLength":255,"type":"string"}},"required":["amount","amountTaxFree","isTestPayment","orderNo","productDesc"],"type":"object"},"TossApiSuccessMakePaymentResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/MakePaymentResponse"}},"required":["resultType","success"],"type":"object"},"MakePaymentResponse":{"description":"这是 Toss Pay 支付创建请求响应。","properties":{"payToken":{"description":"这是 Toss Pay 令牌。每次都是唯一的令牌值，商户必须保存并管理该值。","maxLength":30,"type":"string"}},"required":["payToken"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/make-payment":{"post":{"description":"创建支付。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"makePayment","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"支付创建请求已成功处理。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"创建支付","tags":["toss-pay"]}}}} ``` ## 执行支付 > 请求批准已完成支付认证的支付单。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"ExecutePaymentRequest":{"description":"这是针对已完成用户认证的支付的批准请求正文。","properties":{"isTestPayment":{"description":"沙盒环境为 false，正式应用为 true。为 true 时会发生真实支付。","type":"boolean"},"orderNo":{"description":"这是商家的商品订单号。可以使用数字、英文字母和特殊字符（\\_-:.^@）。","maxLength":50,"type":"string"},"payToken":{"description":"这是 Toss Pay 令牌。它是要批准的支付订单的令牌值。","maxLength":30,"type":"string"}},"required":["isTestPayment","payToken"],"type":"object"},"TossApiSuccessExecutePaymentResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/ExecutePaymentResponse"}},"required":["resultType","success"],"type":"object"},"ExecutePaymentResponse":{"description":"这是支付批准请求的响应。","properties":{"accountBankCode":{"description":"这是银行代码。仅在 Toss Money（账户）支付时返回。","type":"string"},"accountBankName":{"description":"这是银行名称。仅在 Toss Money（账户）支付时返回。","type":"string"},"accountNumber":{"description":"这是账户号码。已部分遮罩，仅在 Toss Money（账户）支付时返回。","type":"string"},"amount":{"description":"这是总支付金额。","format":"int32","type":"integer"},"approvalTime":{"description":"这是支付被批准的时间。(yyyy-MM-dd HH:flag\\_mm:ss 格式)","type":"string"},"cardAuthorizationNo":{"description":"这是卡批准编号。仅在卡支付时返回。","type":"string"},"cardBinNumber":{"description":"这是卡 BIN 号码。该值由卡公司提供，可能已被遮罩，仅在卡支付时返回。","type":"string"},"cardCompanyCode":{"description":"这是卡公司代码。仅在卡支付时返回。","format":"int32","type":"integer"},"cardCompanyName":{"description":"这是卡公司名称。仅在卡支付时返回。","type":"string"},"cardMethodType":{"description":"这是卡类型。可为 CREDIT（信用卡）/CHECK（借记卡）/PREPAYMENT（预付卡）之一，仅在卡支付时返回。","type":"string"},"cardNum4Print":{"description":"这是用户选择的卡的后 4 位。仅在卡支付时返回。","type":"string"},"cardNumber":{"description":"这是已遮罩的卡号。仅在卡支付时返回。","type":"string"},"cardUserType":{"description":"这是卡用户区分。可为 PERSONAL（本人卡）/PERSONAL\\_FAMILY（家庭卡）/CORP\\_PERSONAL（法人指定付款账户员工）/CORP\\_PRIVATE（法人共用）/CORP\\_COMPANY（法人指定付款账户公司，仅 Hana Card）之一，仅在卡支付时返回。","type":"string"},"cashReceiptMgtKey":{"description":"这是现金收据管理编号标识值。仅在 Toss Money（账户）支付时返回。","type":"string"},"code":{"description":"这是支付批准处理结果代码。成功为 0，失败为 -1。","format":"int32","type":"integer"},"discountedAmount":{"description":"这是应用了折扣的支付金额。","format":"int32","type":"integer"},"errorCode":{"description":"这是支付失败时返回的错误代码。code 为 -1 时返回。","type":"string"},"mode":{"description":"表示支付被处理的环境。值为 NORMAL 或 TEST 之一。","type":"string"},"msg":{"description":"这是支付失败时包含失败原因的消息。code 为 -1 时返回。","type":"string"},"noInterest":{"description":"这是是否为免息分期。仅在卡支付时返回。","type":"boolean"},"orderNo":{"description":"这是请求的商家商品订单号。","type":"string"},"paidAmount":{"description":"这是以支付方式实际批准的金额。","format":"int32","type":"integer"},"payMethod":{"description":"这是支付方式。值为 CARD 或 TOSS\\_MONEY。","type":"string"},"payToken":{"description":"这是用于识别该支付订单的令牌。","type":"string"},"salesCheckLinkUrl":{"description":"这是销售凭证确认 URL。仅在卡支付时返回。","type":"string"},"spreadOut":{"description":"这是分期期数。0 表示一次性付款，仅在卡支付时返回。","format":"int32","type":"integer"},"stateMsg":{"description":"这是描述支付处理状态的消息。","type":"string"},"transactionId":{"description":"这是用于识别交易的交易 ID。","type":"string"}},"required":["amount","approvalTime","code","discountedAmount","mode","orderNo","paidAmount","payMethod","payToken","stateMsg","transactionId"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/execute-payment":{"post":{"description":"请求批准已完成支付认证的支付单。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"executePayment","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"支付批准请求已成功处理。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"执行支付","tags":["toss-pay"]}}}} ``` ## 查询支付状态 > 可以查询用户请求的支付状态。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"PaymentStatusRequest":{"description":"这是支付状态查询请求参数。","properties":{"isTestPayment":{"description":"表示是否为测试支付。","type":"boolean"},"orderNo":{"description":"这是订单号。请求时，这个值和 `payToken` 二者之一为必填。","type":"string"},"payToken":{"description":"这是用于识别支付的键。请求时，这个值和 `orderNo` 二者之一为必填。","type":"string"}},"required":["isTestPayment"],"type":"object"},"TossApiSuccessPaymentStatusResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/PaymentStatusResponse"}},"required":["resultType","success"],"type":"object"},"PaymentStatusResponse":{"description":"这是支付状态查询响应信息。","properties":{"accountBankCode":{"description":"如果是账户支付，则为银行代码。","type":"string"},"accountBankName":{"description":"如果是账户支付，则为银行名称。","type":"string"},"accountNumber":{"description":"这是账户号码。","type":"string"},"amount":{"description":"这是总支付金额。","format":"int32","type":"integer"},"amountServiceFee":{"description":"这是服务手续费金额。","format":"int32","type":"integer"},"amountTaxFree":{"description":"这是免税金额。","format":"int32","type":"integer"},"amountTaxable":{"description":"这是应税金额。","format":"int32","type":"integer"},"amountVat":{"description":"这是增值税金额。","format":"int32","type":"integer"},"card":{"$ref":"#/components/schemas/CardInfo","description":"这是卡支付信息。"},"createdTs":{"description":"这是支付创建时间（ISO 8601 格式）。","type":"string"},"discountAmountV2":{"description":"这是在最新折扣系统中应用的折扣金额。","format":"int32","type":"integer"},"discountedAmount":{"description":"这是应用折扣后的金额。","format":"int32","type":"integer"},"disposableCupDeposit":{"description":"这是一次性杯子押金金额。","format":"int32","type":"integer"},"mode":{"description":"表示支付处理环境。是 NORMAL 或 TEST 之一。","type":"string"},"orderNo":{"description":"这是订单号。","type":"string"},"paidAmount":{"description":"这是实际用户支付的金额。","format":"int32","type":"integer"},"paidPointV2":{"description":"这是使用储值/积分支付的金额。","format":"int32","type":"integer"},"paidTs":{"description":"这是支付完成时间（ISO 8601 格式）。","type":"string"},"payMethod":{"description":"这是支付方式。例如：CARD, ACCOUNT\\_TRANSFER","type":"string"},"payStatus":{"description":"这是支付状态。例如：DONE, CANCELLED, FAILED 等","type":"string"},"payToken":{"description":"这是用于识别支付的键。","type":"string"},"refundableAmount":{"description":"这是当前可退款金额。","format":"int32","type":"integer"},"transactions":{"description":"这是按支付处理阶段划分的交易列表。","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":"这是卡片支付的详细信息。","properties":{"cardAuthorizationNo":{"description":"这是卡片批准编号。","type":"string"},"cardBinNumber":{"description":"这是卡片 BIN 号码。","type":"string"},"cardCompanyCode":{"description":"这是卡公司代码。","format":"int32","type":"integer"},"cardCompanyName":{"description":"这是卡公司名称。","type":"string"},"cardMethodType":{"description":"这是卡支付方式。","type":"string"},"cardNum4Print":{"description":"这是用户选择的卡的后 4 位。","type":"string"},"cardNumber":{"description":"这是已遮罩的卡号。","type":"string"},"cardUserType":{"description":"是个人/法人吗。","type":"string"},"noInterest":{"description":"这是是否为免息分期。","type":"boolean"},"salesCheckLinkUrl":{"description":"这是销售凭证 URL。","type":"string"},"spreadOut":{"description":"这是分期期数。","format":"int32","type":"integer"}},"required":["cardAuthorizationNo","cardBinNumber","cardCompanyCode","cardCompanyName","cardMethodType","cardNum4Print","cardNumber","cardUserType","noInterest","salesCheckLinkUrl","spreadOut"]},"TransactionInfo":{"description":"这是按支付处理阶段划分的交易信息。","properties":{"discountedAmount":{"description":"这是该阶段应用的折扣金额。","format":"int32","type":"integer"},"paidAmount":{"description":"这是该阶段实际支付的金额。","format":"int32","type":"integer"},"pointAmount":{"description":"这是该阶段使用的积分金额。","format":"int32","type":"integer"},"regTs":{"description":"这是交易注册时间（ISO 8601 格式）。","type":"string"},"stepType":{"description":"这是支付处理阶段。例如：INIT, PAID","type":"string"},"transactionAmount":{"description":"这是该阶段的总支付金额。","format":"int32","type":"integer"},"transactionId":{"description":"这是交易标识符。","type":"string"}},"required":["discountedAmount","paidAmount","pointAmount","regTs","stepType","transactionAmount","transactionId"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/get-payment-status":{"post":{"description":"可以查询用户请求的支付状态。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"getPaymentStatus","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"返回支付状态信息。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"查询支付状态","tags":["toss-pay"]}}}} ``` ## 支付退款 > 可以对支付单发起退款。请提前确认可退款与余额条件等。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"RefundPaymentRequest":{"description":"这是用于 Toss Pay 退款的请求正文。","properties":{"amount":{"description":"这是要退款的金额。未填写时，将退款到该支付单剩余的全部金额。部分退款时请务必使用 amount。","format":"int64","type":"integer"},"isTestPayment":{"description":"沙盒环境为 false，正式应用为 true。为 true 时会发生真实支付。","type":"boolean"},"payToken":{"description":"这是 Toss Pay 令牌。它是要批准的支付订单的令牌值。","maxLength":30,"type":"string"},"reason":{"description":"这是退款原因。","maxLength":55,"type":"string"}},"required":["isTestPayment","payToken"],"type":"object"},"TossApiSuccessRefundPaymentResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RefundPaymentResponse"}},"required":["resultType","success"],"type":"object"},"RefundPaymentResponse":{"description":"这是支付退款请求响应。","properties":{"accountBankCode":{"description":"这是银行代码。","maxLength":3,"type":"string"},"accountBankName":{"description":"这是银行名称。","maxLength":20,"type":"string"},"accountNumber":{"description":"这是账户号码。包含部分遮罩。","maxLength":30,"type":"string"},"approvalTime":{"description":"这是该支付单退款处理时间。（yyyy-MM-dd HH:flag\\_mm:ss 格式)","type":"string"},"cardBinNumber":{"description":"这是卡 BIN 号码。由卡公司提供，可能已被遮罩。","maxLength":8,"type":"string"},"cardMethodType":{"description":"这是卡类型。是 CREDIT（信用卡）/CHECK（借记卡）/PREPAYMENT（预付卡）之一。","maxLength":10,"type":"string"},"cardNum4Print":{"description":"这是用户选择的卡的后 4 位。","maxLength":4,"type":"string"},"cardNumber":{"description":"这是已遮罩的卡号。","maxLength":20,"type":"string"},"cardUserType":{"description":"这是卡用户区分。是 PERSONAL（本人卡）/PERSONAL\\_FAMILY（家属卡）/CORP\\_PERSONAL（法人指定支付账户员工）/CORP\\_PRIVATE（法人共用）/CORP\\_COMPANY（法人指定支付账户公司（仅 Hana Card））之一。","maxLength":20,"type":"string"},"cashReceiptMgtKey":{"description":"这是现金收据管理号码的识别值。","maxLength":36,"type":"string"},"discountedAmount":{"description":"这是折扣后的金额。","format":"int32","maxLength":7,"type":"integer"},"paidAmount":{"description":"这是支付方式批准金额。","format":"int32","maxLength":7,"type":"integer"},"payToken":{"description":"这是被退款的支付令牌。","maxLength":30,"type":"string"},"refundNo":{"description":"这是退款编号。","type":"string"},"refundableAmount":{"description":"这是可退款金额。","format":"int32","maxLength":7,"type":"integer"},"refundedAmount":{"description":"这是退款请求金额。","format":"int32","maxLength":7,"type":"integer"},"refundedDiscountAmount":{"description":"这是退款请求金额中实际扣除的折扣金额。","format":"int32","maxLength":7,"type":"integer"},"refundedPaidAmount":{"description":"这是退款请求金额中实际扣除的支付方式金额。","format":"int32","maxLength":7,"type":"integer"},"transactionId":{"description":"这是交易事务 ID。","maxLength":36,"type":"string"}},"required":["approvalTime","discountedAmount","paidAmount","payToken","refundNo","refundableAmount","refundedAmount","refundedDiscountAmount","refundedPaidAmount","transactionId"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/refund-payment":{"post":{"description":"可以对支付单发起退款。请提前确认可退款与余额条件等。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"refundPayment","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"退款请求已成功处理。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"支付退款","tags":["toss-pay"]}}}} ``` ## 创建计费密钥 > 自动支付用的计费密钥。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"CreateBillingKeyRequest":{"description":"这是创建计费密钥的请求正文。","properties":{"isTestPayment":{"description":"是否为测试支付。","type":"boolean"},"productDesc":{"description":"这是自动扣款商品名称。","type":"string"},"returnFailureUrl":{"description":"这是认证失败时要跳转的 URL。","type":"string"},"returnSuccessUrl":{"description":"这是认证成功后要跳转的 URL。","type":"string"}},"required":["isTestPayment","productDesc"]},"TossApiSuccessCreateBillingKeyResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/CreateBillingKeyResponse"}},"required":["resultType","success"],"type":"object"},"CreateBillingKeyResponse":{"description":"这是创建计费密钥的响应。","properties":{"checkoutAndroidUri":{"description":"这是 Android 认证 URI。","type":"string"},"checkoutIosUri":{"description":"这是 iOS 认证 URI。","type":"string"},"checkoutUri":{"description":"这是 Toss 应用认证 URI。","type":"string"},"wrappedToken":{"description":"这是包装后的计费密钥令牌。","type":"string"}},"required":["wrappedToken"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/create-billing-key":{"post":{"description":"自动支付用的计费密钥。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"createBillingKey","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"这是请求处理结果。请根据 `resultType` 值区分成功/失败。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"创建计费密钥","tags":["toss-pay"]}}}} ``` ## 查询计费密钥状态 > 查询计费密钥的当前状态。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`5006\` | 找不到计费密钥。 |\ > \| \`5005\` | 这是已停用的计费密钥。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 这个 API 可以原样传递已联动内部系统的错误代码。未文档化的 \`errorCode\` 视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"BillingKeyStatusRequest":{"description":"这是查询计费密钥状态的请求正文。","properties":{"isTestPayment":{"description":"是否为测试支付。","type":"boolean"},"wrappedToken":{"description":"这是包装后的计费密钥令牌。","type":"string"}},"required":["isTestPayment","wrappedToken"]},"TossApiSuccessBillingKeyStatusResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/BillingKeyStatusResponse"}},"required":["resultType","success"],"type":"object"},"BillingKeyStatusResponse":{"description":"这是查询计费密钥状态的响应。","properties":{"accountBankCode":{"description":"这是银行代码。仅在以账户注册的计费密钥时返回。","type":"string"},"accountBankName":{"description":"这是银行名称。仅在以账户注册的计费密钥时返回。","type":"string"},"accountImgUrl":{"description":"这是银行图片 URL。仅在以账户注册的计费密钥时返回。","type":"string"},"accountName":{"description":"这是账户持有人姓名。仅在以账户注册的计费密钥时返回。","type":"string"},"accountNumber":{"description":"这是账户号码。已部分遮罩，仅在以账户注册的计费密钥时返回。","type":"string"},"billingKeyStatus":{"description":"这是 Apps in Toss 合作伙伴 API 中使用的计费密钥状态。","enum":["CREATED","AUTHENTICATING","ACTIVE","REMOVED","CANCELED","FAILED","UNKNOWN"],"type":"string"},"cardCompanyName":{"description":"这是卡公司名称。仅在以卡片注册的计费密钥时返回。","type":"string"},"cardCompanyNo":{"description":"这是卡公司代码。仅在以卡片注册的计费密钥时返回。","format":"int32","type":"integer"},"cardImgUrl":{"description":"这是卡图片 URL。仅在以卡片注册的计费密钥时返回。","type":"string"},"cardName":{"description":"这是卡名称。仅在以卡片注册的计费密钥时返回。","type":"string"},"cardNumber":{"description":"这是已遮罩的卡号。仅在以卡片注册的计费密钥时返回。","type":"string"}},"required":["billingKeyStatus"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/get-billing-key-status":{"post":{"description":"查询计费密钥的当前状态。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `5006` | 找不到计费密钥。 |\n| `5005` | 这是已停用的计费密钥。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n这个 API 可以原样传递已联动内部系统的错误代码。未文档化的 `errorCode` 视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"getBillingKeyStatus","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"这是请求处理结果。请根据 `resultType` 值区分成功/失败。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"查询计费密钥状态","tags":["toss-pay"]}}}} ``` ## 批准自动支付 > 使用计费密钥来批准支付。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`5006\` | 找不到计费密钥。 |\ > \| \`5005\` | 这是已停用的计费密钥。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 这个 API 可以原样传递已联动内部系统的错误代码。未文档化的 \`errorCode\` 视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"ExecuteBillingRequest":{"description":"这是自动扣款批准请求正文。","properties":{"amount":{"description":"这是支付金额。","format":"int64","type":"integer"},"amountServiceFee":{"description":"这是服务费。","format":"int64","type":"integer"},"amountTaxFree":{"description":"这是免税金额。","format":"int64","type":"integer"},"amountTaxable":{"description":"这是应税金额。","format":"int64","type":"integer"},"amountVat":{"description":"这是增值税。","format":"int64","type":"integer"},"cashReceipt":{"description":"这是是否开具现金收据。若无值则按 true 处理。","type":"boolean"},"cashReceiptTradeOption":{"description":"这是现金收据开具类型。可为 GENERAL/CULTURE/PUBLIC\\_TP 之一，若无值则按 GENERAL 处理。","type":"string"},"isTestPayment":{"description":"是否为测试支付。","type":"boolean"},"orderNo":{"description":"这是订单号。","type":"string"},"productDesc":{"description":"这是商品说明。","type":"string"},"sendFailPush":{"description":"这是支付失败时是否发送推送。若无值则按 true 处理。","type":"boolean"},"spreadOut":{"description":"这是分期期数。0 表示一次性付款。","format":"int32","type":"integer"},"wrappedToken":{"description":"这是包装后的计费密钥令牌。","type":"string"}},"required":["amount","amountTaxFree","isTestPayment","orderNo","productDesc","spreadOut","wrappedToken"]},"TossApiSuccessExecuteBillingResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/ExecuteBillingResponse"}},"required":["resultType","success"],"type":"object"},"ExecuteBillingResponse":{"description":"这是自动扣款批准响应。","properties":{"accountBankCode":{"description":"这是银行代码。仅在 Toss Money（账户）支付时返回。","type":"string"},"accountBankName":{"description":"这是银行名称。仅在 Toss Money（账户）支付时返回。","type":"string"},"accountNumber":{"description":"这是账户号码。已部分遮罩，仅在 Toss Money（账户）支付时返回。","type":"string"},"amount":{"description":"这是总支付金额。","format":"int64","type":"integer"},"approvalTime":{"description":"这是自动扣款获批时间。(yyyy-MM-dd HH:flag\\_mm:ss 格式)","type":"string"},"cardAuthorizationNo":{"description":"这是卡批准编号。仅在卡支付时返回。","type":"string"},"cardBinNumber":{"description":"这是卡 BIN 号码。该值由卡公司提供，可能已被遮罩，仅在卡支付时返回。","type":"string"},"cardCompanyCode":{"description":"这是卡公司代码。仅在卡支付时返回。","format":"int32","type":"integer"},"cardCompanyName":{"description":"这是卡公司名称。仅在卡支付时返回。","type":"string"},"cardMethodType":{"description":"这是卡类型。可为 CREDIT（信用卡）/CHECK（借记卡）/PREPAYMENT（预付卡）之一，仅在卡支付时返回。","type":"string"},"cardNum4Print":{"description":"这是用户选择的卡的后 4 位。仅在卡支付时返回。","type":"string"},"cardNumber":{"description":"这是已遮罩的卡号。仅在卡支付时返回。","type":"string"},"cardUserType":{"description":"这是卡用户区分。可为 PERSONAL（本人卡）/PERSONAL\\_FAMILY（家庭卡）/CORP\\_PERSONAL（法人指定付款账户员工）/CORP\\_PRIVATE（法人共用）/CORP\\_COMPANY（法人指定付款账户公司，仅 Hana Card）之一，仅在卡支付时返回。","type":"string"},"cashReceiptMgtKey":{"description":"这是现金收据管理编号标识值。仅在 Toss Money（账户）支付时返回。","type":"string"},"code":{"description":"这是自动扣款批准处理结果代码。成功为 0，失败为 -1。","format":"int32","type":"integer"},"discountedAmount":{"description":"这是应用了折扣的支付金额。","format":"int64","type":"integer"},"errorCode":{"description":"这是自动扣款失败时返回的错误代码。code 为 -1 时返回。","type":"string"},"mode":{"description":"表示支付被处理的环境。值为 NORMAL 或 TEST 之一。","type":"string"},"msg":{"description":"这是自动扣款失败时包含失败原因的消息。code 为 -1 时返回。","type":"string"},"noInterest":{"description":"这是是否为免息分期。仅在卡支付时返回。","type":"boolean"},"orderNo":{"description":"这是请求的订单号。","type":"string"},"paidAmount":{"description":"这是以支付方式实际批准的金额。","format":"int64","type":"integer"},"payMethod":{"description":"这是支付方式。值为 CARD 或 TOSS\\_MONEY。","type":"string"},"payToken":{"description":"这是用于识别该自动扣款订单的令牌。","type":"string"},"salesCheckLinkUrl":{"description":"这是销售凭证确认 URL。仅在卡支付时返回。","type":"string"},"spreadOut":{"description":"这是分期期数。0 表示一次性付款，仅在卡支付时返回。","format":"int32","type":"integer"},"transactionId":{"description":"这是用于识别交易的交易 ID。","type":"string"}},"required":["code"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/execute-billing":{"post":{"description":"使用计费密钥来批准支付。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `5006` | 找不到计费密钥。 |\n| `5005` | 这是已停用的计费密钥。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n这个 API 可以原样传递已联动内部系统的错误代码。未文档化的 `errorCode` 视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"executeBilling","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"这是请求处理结果。请根据 `resultType` 值区分成功/失败。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"批准自动支付","tags":["toss-pay"]}}}} ``` ## 自动支付退款 > 对已通过自动支付批准的支付单进行退款。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"RefundBillingRequest":{"description":"这是自动支付退款请求正文。","properties":{"isTestPayment":{"description":"是否为测试支付。","type":"boolean"},"payToken":{"description":"这是要退款的自动支付对应的 Toss Pay 令牌。","type":"string"},"reason":{"description":"这是退款原因。","type":"string"}},"required":["isTestPayment","payToken"]},"TossApiSuccessRefundBillingResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RefundBillingResponse"}},"required":["resultType","success"],"type":"object"},"RefundBillingResponse":{"description":"这是自动支付退款响应。","properties":{"accountBankCode":{"description":"这是银行代码。","type":"string"},"accountBankName":{"description":"这是银行名称。","type":"string"},"accountNumber":{"description":"这是账户号码。部分已被遮罩。","type":"string"},"approvalTime":{"description":"这是退款处理时间。（yyyy-MM-dd HH:flag\\_mm:ss 格式)","type":"string"},"cardBinNumber":{"description":"这是卡 BIN 号码。由发卡机构提供，可能已被遮罩。","type":"string"},"cardMethodType":{"description":"这是卡类型。是 CREDIT（信用卡）/CHECK（借记卡）/PREPAYMENT（预付卡）之一。","type":"string"},"cardNum4Print":{"description":"这是用户选择的卡的后 4 位。","type":"string"},"cardNumber":{"description":"这是已遮罩的卡号。","type":"string"},"cardUserType":{"description":"这是卡用户区分。是 PERSONAL（本人卡）/PERSONAL\\_FAMILY（家属卡）/CORP\\_PERSONAL（法人指定支付账户员工）/CORP\\_PRIVATE（法人共用）/CORP\\_COMPANY（法人指定支付账户公司（仅 Hana Card））之一。","type":"string"},"cashReceiptMgtKey":{"description":"这是现金收据管理号码的识别值。","type":"string"},"discountedAmount":{"description":"这是折扣后的金额。","format":"int32","type":"integer"},"paidAmount":{"description":"这是支付方式批准金额。","format":"int32","type":"integer"},"payToken":{"description":"这是被退款的支付令牌。","type":"string"},"refundNo":{"description":"这是退款编号。","type":"string"},"refundableAmount":{"description":"这是可退款金额。","format":"int32","type":"integer"},"refundedAmount":{"description":"这是退款请求金额。","format":"int32","type":"integer"},"refundedDiscountAmount":{"description":"这是退款请求金额中实际扣除的折扣金额。","format":"int32","type":"integer"},"refundedPaidAmount":{"description":"这是退款请求金额中实际扣除的支付方式金额。","format":"int32","type":"integer"},"transactionId":{"description":"这是交易事务 ID。","type":"string"}},"required":["approvalTime","discountedAmount","paidAmount","payToken","refundNo","refundableAmount","refundedAmount","refundedDiscountAmount","refundedPaidAmount","transactionId"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/refund-billing":{"post":{"description":"对已通过自动支付批准的支付单进行退款。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"refundBilling","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"这是请求处理结果。请根据 `resultType` 值区分成功/失败。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"自动支付退款","tags":["toss-pay"]}}}} ``` ## 删除计费密钥 > 删除（解除）计费密钥。\ > \ > \### 业务错误代码\ > \ > 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\ > \ > \| errorCode | 说明 |\ > \| --------- | -------------- |\ > \| \`5001\` | 尚未签约 Toss Pay。 |\ > \| \`5006\` | 找不到计费密钥。 |\ > \| \`4010\` | 找不到认证信息。 |\ > \| \`4095\` | 请求已超出限制。请稍后再试。 |\ > \ > 此 API 可以原样传递所集成内部系统的错误代码。未文档化的 \`errorCode\` 会被视为失败，请参考 \`reason\` 消息。\ > \ > \*\*请求限制\*\*: 每个应用每分钟 3,000 次 ```json {"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是处理与 Toss Pay 相关请求的 API。","name":"toss-pay"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"RemoveBillingKeyRequest":{"description":"这是 计费密钥 删除请求正文。","properties":{"isTestPayment":{"description":"是否为测试支付。","type":"boolean"},"wrappedToken":{"description":"这是包装后的计费密钥令牌。","type":"string"}},"required":["isTestPayment","wrappedToken"]},"TossApiSuccessRemoveBillingKeyResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RemoveBillingKeyResponse"}},"required":["resultType","success"],"type":"object"},"RemoveBillingKeyResponse":{"description":"这是 计费密钥 删除响应。","properties":{"code":{"description":"这是 计费密钥 删除处理结果代码。成功时为 0。","format":"int32","type":"integer"},"msg":{"description":"这是在删除 计费密钥 失败时包含失败原因的消息。","type":"string"}},"required":["code"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/pay/remove-billing-key":{"post":{"description":"删除（解除）计费密钥。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --------- | -------------- |\n| `5001` | 尚未签约 Toss Pay。 |\n| `5006` | 找不到计费密钥。 |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所集成内部系统的错误代码。未文档化的 `errorCode` 会被视为失败，请参考 `reason` 消息。\n\n**请求限制**: 每个应用每分钟 3,000 次","operationId":"removeBillingKey","parameters":[{"description":"用于验证用户的密钥。可通过 [获取用户信息](https://developers-apps-in-toss.toss.im/api/zh/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":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","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":"这是请求处理结果。请根据 `resultType` 值区分成功/失败。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"删除计费密钥","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/zh/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.