> 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/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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/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 token。是要授权支付的 token 值。","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":"这是用于识别该支付的 token。","type":"string"},"salesCheckLinkUrl":{"description":"这是签购单确认 URL。仅在银行卡支付时返回。","type":"string"},"spreadOut":{"description":"这是分期月数。0 表示一次性付款，仅在银行卡支付时返回。","format":"int32","type":"integer"},"stateMsg":{"description":"这是说明支付处理状态的消息。","type":"string"},"transactionId":{"description":"这是用于识别交易的 transaction 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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/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 token。是要授权支付的 token 值。","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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/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":"这是封装后的计费密钥 token。","type":"string"}},"required":["wrappedToken"]},"TossApiFail":{"description":"这是失败响应封装。业务错误会以 HTTP 200 返回，所以 `resultType`请务必确认。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。 `SUCCESS`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"BillingKeyStatusRequest":{"description":"这是计费密钥状态查询请求体。","properties":{"isTestPayment":{"description":"这是是否为测试支付。","type":"boolean"},"wrappedToken":{"description":"这是封装后的计费密钥 token。","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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/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":"这是封装后的计费密钥 token。","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":"这是用于识别该自动扣款的 token。","type":"string"},"salesCheckLinkUrl":{"description":"这是签购单确认 URL。仅在银行卡支付时返回。","type":"string"},"spreadOut":{"description":"这是分期月数。0 表示一次性付款，仅在银行卡支付时返回。","format":"int32","type":"integer"},"transactionId":{"description":"这是用于识别交易的 transaction ID。","type":"string"}},"required":["code"]},"TossApiFail":{"description":"这是失败响应封装。业务错误会以 HTTP 200 返回，所以 `resultType`请务必确认。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。 `SUCCESS`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"RemoveBillingKeyRequest":{"description":"这是计费密钥删除请求正文。","properties":{"isTestPayment":{"description":"这是是否为测试支付。","type":"boolean"},"wrappedToken":{"description":"这是封装后的计费密钥 token。","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`除 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`除 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/documentation/api/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":"这是用于认证用户的密钥。Mini App SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/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.