{"openapi":"3.1.0","info":{"title":"KukoPay Merchant API","version":"1.0.0","description":"面向商户服务端的支付接口。\n\n**环境由密钥决定**：`kuko_test_` 开头的密钥只能产生沙箱数据，`kuko_live_` 开头的密钥产生真实交易，\n请求体里没有、也不会有切换环境的字段。\n\n**金额一律是整数最小货币单位**（美分），不要传小数。\n\n**每个响应都带 `request_id`**，同时出现在响应体和 `X-Request-Id` 响应头中，请记入你的日志。","contact":{"name":"KukoPay Support","url":"https://kukopay.com/docs"}},"servers":[{"url":"https://api.kukopay.com/v1","description":"生产环境（沙箱与正式共用，由密钥区分）"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Orders","description":"下单与订单查询"},{"name":"Refunds","description":"退款"},{"name":"Disputes","description":"拒付 / 争议"},{"name":"Balance","description":"余额与资金流水"},{"name":"PaymentLinks","description":"免代码收款链接"},{"name":"Webhooks","description":"事件接收端点与签名密钥"},{"name":"Events","description":"事件流，Webhook 的补偿通道"},{"name":"Logs","description":"自助排障：你自己的 API 调用记录"}],"paths":{"/orders":{"post":{"tags":["Orders"],"summary":"统一下单","description":"创建一笔支付订单并返回托管收银台地址。\n\n重复提交相同的 `out_trade_no` 且订单内容一致时返回原订单；\n如果金额、币种、标题或回调地址不同，返回 409 conflict。仍建议带上 Idempotency-Key，以便安全重试其他写请求。","operationId":"createOrder","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":1,"maximum":100000000000,"description":"订单金额，必须是最小货币单位的正整数；字符串和小数会被拒绝（以最小货币单位计，例如美分）"},"out_trade_no":{"type":"string","description":"商户订单号，长度 1 到 128 字符；超长会被拒绝，不会截断。省略则由平台生成，但那样就失去了业务订单号的幂等能力。","minLength":1,"maxLength":128},"currency":{"type":"string","enum":["USD","HKD","CNY"],"default":"USD","description":"币种。沙箱可用全部支持的币种；正式环境仅限平台为你开通的币种"},"subject":{"type":"string","description":"商品标题，最长 255 字符；超长会被拒绝","maxLength":255},"notify_url":{"type":"string","description":"订单级异步通知地址，必须是公网 HTTPS。正式订单可省略，但需有已启用且订阅 payment.succeeded 的正式环境 Webhook 端点。"},"return_url":{"type":"string","description":"支付成功后买家跳回的地址。可包含占位符 {TRADE_NO}、{OUT_TRADE_NO}，跳转时替换为本订单的值；收银台显示支付成功后约 5 秒自动跳转"},"metadata":{"$ref":"#/components/schemas/Metadata"}}}}}},"responses":{"200":{"description":"该 out_trade_no 已存在且订单内容一致，返回原订单","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"订单已存在（幂等返回）"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔支付订单。收银台、查询接口与 payment.* 事件返回的是同一个结构。","properties":{"object":{"const":"order"},"trade_no":{"type":"string","description":"平台交易号。沙箱以 TRD_SB_ 开头，正式以 TRD_ 开头。"},"out_trade_no":{"type":"string","description":"商户自己的订单号，在同一商户同一环境下唯一"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"订单金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"平台收单手续费，入账后才有值（以最小货币单位计，例如美分）"},"net_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"实际入账净额 = amount - fee（以最小货币单位计，例如美分）"},"refunded_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"已退款总额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码","example":"USD"},"subject":{"type":"string","description":"商品标题"},"status":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"],"description":"订单状态"},"mode":{"enum":["sandbox","live"],"description":"由调用所用的密钥决定，不接受请求体指定"},"payment_id":{"type":["string","null"],"description":"当前关联的上游渠道支付号。买家更换支付方式后会变化，对账请以 trade_no 为准"},"payment_method":{"type":["string","null"],"enum":["card","alipay","wechat_pay","apple_pay","google_pay",null],"description":"买家实际使用的支付方式，支付成功后才有值"},"refundable_until":{"type":["string","null"],"format":"date-time","description":"最晚可退款时间。仅部分支付方式有期限（如支付宝、微信支付），无期限为 null"},"checkout_url":{"type":"string","description":"托管收银台地址。已签名且会过期，不要长期缓存。"},"expires_at":{"type":"string","format":"date-time","description":"收银台链接失效时间。此后买家无法再发起支付，未支付的订单由平台关闭为 expired"},"notify_url":{"type":["string","null"],"description":"该订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"paid_at":{"type":["string","null"],"format":"date-time","description":"支付成功时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"}}}}}}}},"201":{"description":"订单已创建","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"下单成功"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔支付订单。收银台、查询接口与 payment.* 事件返回的是同一个结构。","properties":{"object":{"const":"order"},"trade_no":{"type":"string","description":"平台交易号。沙箱以 TRD_SB_ 开头，正式以 TRD_ 开头。"},"out_trade_no":{"type":"string","description":"商户自己的订单号，在同一商户同一环境下唯一"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"订单金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"平台收单手续费，入账后才有值（以最小货币单位计，例如美分）"},"net_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"实际入账净额 = amount - fee（以最小货币单位计，例如美分）"},"refunded_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"已退款总额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码","example":"USD"},"subject":{"type":"string","description":"商品标题"},"status":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"],"description":"订单状态"},"mode":{"enum":["sandbox","live"],"description":"由调用所用的密钥决定，不接受请求体指定"},"payment_id":{"type":["string","null"],"description":"当前关联的上游渠道支付号。买家更换支付方式后会变化，对账请以 trade_no 为准"},"payment_method":{"type":["string","null"],"enum":["card","alipay","wechat_pay","apple_pay","google_pay",null],"description":"买家实际使用的支付方式，支付成功后才有值"},"refundable_until":{"type":["string","null"],"format":"date-time","description":"最晚可退款时间。仅部分支付方式有期限（如支付宝、微信支付），无期限为 null"},"checkout_url":{"type":"string","description":"托管收银台地址。已签名且会过期，不要长期缓存。"},"expires_at":{"type":"string","format":"date-time","description":"收银台链接失效时间。此后买家无法再发起支付，未支付的订单由平台关闭为 expired"},"notify_url":{"type":["string","null"],"description":"该订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"paid_at":{"type":["string","null"],"format":"date-time","description":"支付成功时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Orders"],"summary":"订单列表","description":"按创建时间倒序返回订单，是做对账的起点。游标分页，避免翻页期间新订单导致漏数据。","operationId":"listOrders","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"$ref":"#/components/parameters/Format"},{"name":"status","in":"query","schema":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"]},"description":"只返回该状态的订单"},{"name":"out_trade_no","in":"query","schema":{"type":"string"},"description":"按商户订单号精确匹配"},{"name":"metadata[key]","in":"query","schema":{"type":"string"},"style":"form","explode":true,"description":"按你挂上去的 metadata 精确匹配，例如 `?metadata[customer_id]=cus_42`。\n可以传多个，含义是「同时满足」。"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"order"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}},"text/csv":{"schema":{"type":"string"},"example":"带 UTF-8 BOM 的 CSV 文件，金额列已换算成两位小数"}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{trade_no}":{"get":{"tags":["Orders"],"summary":"订单查询","description":"既接受平台交易号，也接受商户订单号——下单超时后你手上往往只有后者。","operationId":"retrieveOrder","parameters":[{"name":"trade_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台交易号或商户订单号"}],"responses":{"200":{"description":"订单详情","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔支付订单。收银台、查询接口与 payment.* 事件返回的是同一个结构。","properties":{"object":{"const":"order"},"trade_no":{"type":"string","description":"平台交易号。沙箱以 TRD_SB_ 开头，正式以 TRD_ 开头。"},"out_trade_no":{"type":"string","description":"商户自己的订单号，在同一商户同一环境下唯一"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"订单金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"平台收单手续费，入账后才有值（以最小货币单位计，例如美分）"},"net_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"实际入账净额 = amount - fee（以最小货币单位计，例如美分）"},"refunded_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"已退款总额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码","example":"USD"},"subject":{"type":"string","description":"商品标题"},"status":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"],"description":"订单状态"},"mode":{"enum":["sandbox","live"],"description":"由调用所用的密钥决定，不接受请求体指定"},"payment_id":{"type":["string","null"],"description":"当前关联的上游渠道支付号。买家更换支付方式后会变化，对账请以 trade_no 为准"},"payment_method":{"type":["string","null"],"enum":["card","alipay","wechat_pay","apple_pay","google_pay",null],"description":"买家实际使用的支付方式，支付成功后才有值"},"refundable_until":{"type":["string","null"],"format":"date-time","description":"最晚可退款时间。仅部分支付方式有期限（如支付宝、微信支付），无期限为 null"},"checkout_url":{"type":"string","description":"托管收银台地址。已签名且会过期，不要长期缓存。"},"expires_at":{"type":"string","format":"date-time","description":"收银台链接失效时间。此后买家无法再发起支付，未支付的订单由平台关闭为 expired"},"notify_url":{"type":["string","null"],"description":"该订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"paid_at":{"type":["string","null"],"format":"date-time","description":"支付成功时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Orders"],"summary":"更新订单","description":"目前只有 `metadata` 可以更新。\n金额、币种和环境是已经告知上游渠道的事实，允许在这里改会让我们的记录与真实资金脱节。","operationId":"updateOrder","parameters":[{"name":"trade_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台交易号或商户订单号"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["metadata"],"properties":{"metadata":{"allOf":[{"$ref":"#/components/schemas/Metadata"}],"description":"增量合并，不是整体替换：只出现在请求里的键会被写入，\n值传 `null` 表示删除该键，没提到的键保持不变。\n整个字段传 `null` 表示清空。"}}}}}},"responses":{"200":{"description":"更新后的订单","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"更新成功"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔支付订单。收银台、查询接口与 payment.* 事件返回的是同一个结构。","properties":{"object":{"const":"order"},"trade_no":{"type":"string","description":"平台交易号。沙箱以 TRD_SB_ 开头，正式以 TRD_ 开头。"},"out_trade_no":{"type":"string","description":"商户自己的订单号，在同一商户同一环境下唯一"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"订单金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"平台收单手续费，入账后才有值（以最小货币单位计，例如美分）"},"net_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"实际入账净额 = amount - fee（以最小货币单位计，例如美分）"},"refunded_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"已退款总额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码","example":"USD"},"subject":{"type":"string","description":"商品标题"},"status":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"],"description":"订单状态"},"mode":{"enum":["sandbox","live"],"description":"由调用所用的密钥决定，不接受请求体指定"},"payment_id":{"type":["string","null"],"description":"当前关联的上游渠道支付号。买家更换支付方式后会变化，对账请以 trade_no 为准"},"payment_method":{"type":["string","null"],"enum":["card","alipay","wechat_pay","apple_pay","google_pay",null],"description":"买家实际使用的支付方式，支付成功后才有值"},"refundable_until":{"type":["string","null"],"format":"date-time","description":"最晚可退款时间。仅部分支付方式有期限（如支付宝、微信支付），无期限为 null"},"checkout_url":{"type":"string","description":"托管收银台地址。已签名且会过期，不要长期缓存。"},"expires_at":{"type":"string","format":"date-time","description":"收银台链接失效时间。此后买家无法再发起支付，未支付的订单由平台关闭为 expired"},"notify_url":{"type":["string","null"],"description":"该订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"paid_at":{"type":["string","null"],"format":"date-time","description":"支付成功时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{trade_no}/expire":{"post":{"tags":["Orders"],"summary":"关闭订单","description":"让一笔待支付订单立即失效：收银台链接不再接受支付，订单变为 `expired`，并照常发出 `payment.expired` 事件。\n\n关闭前平台会先向通道确认支付状态。买家其实已经付款时，订单照常入账并返回 `409 conflict`，不会被关闭；\n买家正在完成钱包跳转或 3DS 验证、通道暂时无法取消时，同样返回 `409`，稍后重试即可。\n对已经是 `expired` 的订单重复调用会原样返回该订单。","operationId":"expireOrder","parameters":[{"name":"trade_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台交易号或商户订单号"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"已关闭的订单","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"订单已关闭"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔支付订单。收银台、查询接口与 payment.* 事件返回的是同一个结构。","properties":{"object":{"const":"order"},"trade_no":{"type":"string","description":"平台交易号。沙箱以 TRD_SB_ 开头，正式以 TRD_ 开头。"},"out_trade_no":{"type":"string","description":"商户自己的订单号，在同一商户同一环境下唯一"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"订单金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"平台收单手续费，入账后才有值（以最小货币单位计，例如美分）"},"net_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"实际入账净额 = amount - fee（以最小货币单位计，例如美分）"},"refunded_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"已退款总额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码","example":"USD"},"subject":{"type":"string","description":"商品标题"},"status":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"],"description":"订单状态"},"mode":{"enum":["sandbox","live"],"description":"由调用所用的密钥决定，不接受请求体指定"},"payment_id":{"type":["string","null"],"description":"当前关联的上游渠道支付号。买家更换支付方式后会变化，对账请以 trade_no 为准"},"payment_method":{"type":["string","null"],"enum":["card","alipay","wechat_pay","apple_pay","google_pay",null],"description":"买家实际使用的支付方式，支付成功后才有值"},"refundable_until":{"type":["string","null"],"format":"date-time","description":"最晚可退款时间。仅部分支付方式有期限（如支付宝、微信支付），无期限为 null"},"checkout_url":{"type":"string","description":"托管收银台地址。已签名且会过期，不要长期缓存。"},"expires_at":{"type":"string","format":"date-time","description":"收银台链接失效时间。此后买家无法再发起支付，未支付的订单由平台关闭为 expired"},"notify_url":{"type":["string","null"],"description":"该订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"paid_at":{"type":["string","null"],"format":"date-time","description":"支付成功时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/refunds":{"post":{"tags":["Refunds"],"summary":"申请退款","description":"对已支付订单发起全额或部分退款。\n\n返回 `202` 且 `status=pending` 表示通道已受理但尚未确认：**此时钱还没退出去**，\n该金额已从可用余额转入冻结，最终结果通过 `refund.succeeded` / `refund.failed` 事件告知。\n\n订单存在未结案拒付时会返回 `409 conflict`——那笔钱已被上游扣留，再退一次等于付两次。","operationId":"createRefund","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["trade_no"],"properties":{"trade_no":{"type":"string","description":"原交易号"},"amount":{"type":"integer","format":"int64","minimum":1,"maximum":100000000000,"description":"退款金额。省略则退剩余全部可退金额。（以最小货币单位计，例如美分）"},"reason":{"type":"string","description":"退款原因"},"out_refund_no":{"type":"string","description":"商户退款号，正式退款必填，最长 128 字符。重复提交返回原退款单。"},"metadata":{"$ref":"#/components/schemas/Metadata"}}}}}},"responses":{"200":{"description":"退款已完成，或幂等返回原退款单","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔退款。查询接口与 refund.* 事件返回的是同一个结构。","properties":{"object":{"const":"refund"},"refund_no":{"type":"string","description":"平台退款号"},"out_refund_no":{"type":["string","null"],"description":"商户自己的退款号"},"processor_refund_id":{"type":["string","null"],"description":"上游渠道退款号"},"trade_no":{"type":"string","description":"原交易号"},"out_trade_no":{"type":["string","null"],"description":"原订单的商户订单号"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"本次退款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"reason":{"type":["string","null"],"description":"退款原因"},"status":{"enum":["pending","succeeded","failed"],"description":"退款状态"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"通道已受理但尚未确认时为 true：该金额已从可用余额转入冻结，尚未真实扣账。"},"error_message":{"type":["string","null"],"description":"失败原因"},"order_status":{"type":["string","null"],"description":"原订单当前状态"},"order_amount":{"type":["integer","null"],"description":"原订单金额"},"refunded_amount":{"type":["integer","null"],"description":"该订单已退总额"},"remaining_amount":{"type":["integer","null"],"description":"该订单剩余可退金额"},"metadata":{"$ref":"#/components/schemas/Metadata"},"settled_at":{"type":["string","null"],"format":"date-time","description":"退款真实完成时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"202":{"description":"通道已受理，等待确认；金额已转入冻结但尚未扣账","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔退款。查询接口与 refund.* 事件返回的是同一个结构。","properties":{"object":{"const":"refund"},"refund_no":{"type":"string","description":"平台退款号"},"out_refund_no":{"type":["string","null"],"description":"商户自己的退款号"},"processor_refund_id":{"type":["string","null"],"description":"上游渠道退款号"},"trade_no":{"type":"string","description":"原交易号"},"out_trade_no":{"type":["string","null"],"description":"原订单的商户订单号"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"本次退款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"reason":{"type":["string","null"],"description":"退款原因"},"status":{"enum":["pending","succeeded","failed"],"description":"退款状态"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"通道已受理但尚未确认时为 true：该金额已从可用余额转入冻结，尚未真实扣账。"},"error_message":{"type":["string","null"],"description":"失败原因"},"order_status":{"type":["string","null"],"description":"原订单当前状态"},"order_amount":{"type":["integer","null"],"description":"原订单金额"},"refunded_amount":{"type":["integer","null"],"description":"该订单已退总额"},"remaining_amount":{"type":["integer","null"],"description":"该订单剩余可退金额"},"metadata":{"$ref":"#/components/schemas/Metadata"},"settled_at":{"type":["string","null"],"format":"date-time","description":"退款真实完成时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Refunds"],"summary":"退款列表","description":"按创建时间倒序返回退款单。","operationId":"listRefunds","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"$ref":"#/components/parameters/Format"},{"name":"status","in":"query","schema":{"enum":["pending","succeeded","failed"]},"description":"只返回该状态的退款"},{"name":"trade_no","in":"query","schema":{"type":"string"},"description":"只看某一笔原订单下的退款"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"refund"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}}}}}},"text/csv":{"schema":{"type":"string"},"example":"带 UTF-8 BOM 的 CSV 文件，金额列已换算成两位小数"}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/refunds/{refund_no}":{"get":{"tags":["Refunds"],"summary":"退款查询","description":"既接受平台退款号，也接受商户退款号。受理为 pending 的退款靠它确认最终结果。","operationId":"retrieveRefund","parameters":[{"name":"refund_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台退款号或商户退款号"}],"responses":{"200":{"description":"退款详情","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔退款。查询接口与 refund.* 事件返回的是同一个结构。","properties":{"object":{"const":"refund"},"refund_no":{"type":"string","description":"平台退款号"},"out_refund_no":{"type":["string","null"],"description":"商户自己的退款号"},"processor_refund_id":{"type":["string","null"],"description":"上游渠道退款号"},"trade_no":{"type":"string","description":"原交易号"},"out_trade_no":{"type":["string","null"],"description":"原订单的商户订单号"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"本次退款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"reason":{"type":["string","null"],"description":"退款原因"},"status":{"enum":["pending","succeeded","failed"],"description":"退款状态"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"通道已受理但尚未确认时为 true：该金额已从可用余额转入冻结，尚未真实扣账。"},"error_message":{"type":["string","null"],"description":"失败原因"},"order_status":{"type":["string","null"],"description":"原订单当前状态"},"order_amount":{"type":["integer","null"],"description":"原订单金额"},"refunded_amount":{"type":["integer","null"],"description":"该订单已退总额"},"remaining_amount":{"type":["integer","null"],"description":"该订单剩余可退金额"},"metadata":{"$ref":"#/components/schemas/Metadata"},"settled_at":{"type":["string","null"],"format":"date-time","description":"退款真实完成时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Refunds"],"summary":"更新退款单","description":"与更新订单同样的约定：只支持 `metadata`，增量合并。","operationId":"updateRefund","parameters":[{"name":"refund_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台退款号或商户退款号"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["metadata"],"properties":{"metadata":{"allOf":[{"$ref":"#/components/schemas/Metadata"}],"description":"增量合并，不是整体替换：只出现在请求里的键会被写入，\n值传 `null` 表示删除该键，没提到的键保持不变。\n整个字段传 `null` 表示清空。"}}}}}},"responses":{"200":{"description":"更新后的退款单","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"更新成功"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔退款。查询接口与 refund.* 事件返回的是同一个结构。","properties":{"object":{"const":"refund"},"refund_no":{"type":"string","description":"平台退款号"},"out_refund_no":{"type":["string","null"],"description":"商户自己的退款号"},"processor_refund_id":{"type":["string","null"],"description":"上游渠道退款号"},"trade_no":{"type":"string","description":"原交易号"},"out_trade_no":{"type":["string","null"],"description":"原订单的商户订单号"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"本次退款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"reason":{"type":["string","null"],"description":"退款原因"},"status":{"enum":["pending","succeeded","failed"],"description":"退款状态"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"通道已受理但尚未确认时为 true：该金额已从可用余额转入冻结，尚未真实扣账。"},"error_message":{"type":["string","null"],"description":"失败原因"},"order_status":{"type":["string","null"],"description":"原订单当前状态"},"order_amount":{"type":["integer","null"],"description":"原订单金额"},"refunded_amount":{"type":["integer","null"],"description":"该订单已退总额"},"remaining_amount":{"type":["integer","null"],"description":"该订单剩余可退金额"},"metadata":{"$ref":"#/components/schemas/Metadata"},"settled_at":{"type":["string","null"],"format":"date-time","description":"退款真实完成时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/disputes":{"get":{"tags":["Disputes"],"summary":"拒付列表","description":"买家发起的拒付。开案即冻结争议金额，因此这是需要主动盯的接口——\n用 `status=needs_response` 过滤出还需要你提交证据的案件。","operationId":"listDisputes","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"$ref":"#/components/parameters/Format"},{"name":"status","in":"query","schema":{"enum":["needs_response","under_review","won","lost","closed"]},"description":"只返回该状态的拒付"},{"name":"trade_no","in":"query","schema":{"type":"string"},"description":"只看某一笔订单的拒付"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"dispute"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Dispute"}}}}}}},"text/csv":{"schema":{"type":"string"},"example":"带 UTF-8 BOM 的 CSV 文件，金额列已换算成两位小数"}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/disputes/{dispute_no}":{"get":{"tags":["Disputes"],"summary":"拒付查询","description":"既接受平台拒付号，也接受上游渠道的拒付号。","operationId":"retrieveDispute","parameters":[{"name":"dispute_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台拒付号或上游渠道拒付号"}],"responses":{"200":{"description":"拒付详情","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一笔拒付（Chargeback）。开案时争议金额从可用余额转入冻结，结案时要么释放要么真实扣账。","properties":{"object":{"const":"dispute"},"dispute_no":{"type":"string","description":"平台拒付号"},"trade_no":{"type":"string","description":"被拒付的交易号"},"merchant_id":{"type":"string","description":"商户号"},"processor_dispute_id":{"type":"string","description":"上游渠道的拒付号，可与收单机构后台核对"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"争议金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"拒付处理费，败诉后才有值（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"status":{"enum":["needs_response","under_review","won","lost","closed"],"description":"拒付状态"},"processor_status":{"type":["string","null"],"description":"上游渠道的原始状态"},"reason":{"type":["string","null"],"description":"发卡行给出的拒付原因"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"争议金额是否仍在冻结中"},"evidence_due_by":{"type":["string","null"],"format":"date-time","description":"举证截止时间"},"opened_at":{"type":"string","format":"date-time","description":"开案时间"},"closed_at":{"type":["string","null"],"format":"date-time","description":"结案时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/disputes/{dispute_no}/evidence":{"get":{"tags":["Disputes"],"summary":"查看已提交的证据","operationId":"retrieveDisputeEvidence","parameters":[{"$ref":"#/components/parameters/DisputeNo"}],"responses":{"200":{"description":"当前已组装的证据","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"你为反驳拒付提交的材料。证据本身保存在支付通道侧——发卡行只看得到通道持有的内容；这里是平台的记录。","properties":{"object":{"const":"dispute_evidence"},"dispute_no":{"type":"string","description":"拒付号"},"evidence":{"type":"object","description":"文字材料。可用字段：product_description / customer_name / customer_email_address / customer_purchase_ip / billing_address / shipping_address / shipping_carrier / shipping_tracking_number / shipping_date / service_date / access_activity_log / refund_policy_disclosure / refund_refusal_explanation / cancellation_policy_disclosure / cancellation_rebuttal","additionalProperties":{"type":"string"}},"files":{"type":"array","description":"已上传到通道的证据文件","items":{"type":"object","properties":{"type":{"enum":["receipt","customer_communication","customer_signature","shipping_documentation","service_documentation","cancellation_policy","refund_policy","invoice_showing_distinct_transactions","recurring_transaction_agreement","uncategorized_file"]},"channel_file_id":{"type":"string","description":"通道侧的文件 id"},"file_name":{"type":"string","description":"文件名"},"byte_size":{"type":"integer"}}}},"submitted":{"type":"boolean","description":"false 表示仍是草稿，尚未发给发卡行"},"submitted_at":{"type":["string","null"],"format":"date-time","description":"提交时间"},"updated_at":{"type":["string","null"],"format":"date-time","description":"最后修改时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Disputes"],"summary":"提交证据（申诉）","description":"对拒付提出反驳。**不举证等于败诉**，所以拿到 `dispute.created` 后就该准备材料。\n\n`submit: false` 只暂存草稿，可以分多次补充；`submit: true` 才会发给发卡行，**且不可撤回**。\n\n哪些字段有用取决于拒付原因：「未收到货」靠承运商和运单号，「订阅已取消」靠取消说明。\n\n文件必须先上传到平台存储，再在 `files` 里引用其地址——平台只接受自己存储域名下的地址。","operationId":"submitDisputeEvidence","parameters":[{"$ref":"#/components/parameters/DisputeNo"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"evidence":{"type":"object","description":"文字材料。可用字段：product_description / customer_name / customer_email_address / customer_purchase_ip / billing_address / shipping_address / shipping_carrier / shipping_tracking_number / shipping_date / service_date / access_activity_log / refund_policy_disclosure / refund_refusal_explanation / cancellation_policy_disclosure / cancellation_rebuttal","additionalProperties":{"type":"string","maxLength":5000},"example":{"shipping_carrier":"DHL","shipping_tracking_number":"JD0099887766","shipping_date":"2026-09-02","product_description":"Pro 年度订阅"}},"files":{"type":"array","maxItems":8,"description":"证据文件，单个不超过 10MB","items":{"type":"object","required":["type","url"],"properties":{"type":{"enum":["receipt","customer_communication","customer_signature","shipping_documentation","service_documentation","cancellation_policy","refund_policy","invoice_showing_distinct_transactions","recurring_transaction_agreement","uncategorized_file"]},"url":{"type":"string","description":"平台存储域名下的 HTTPS 地址"}}}},"submit":{"type":"boolean","default":false,"description":"true 才会发给发卡行并把拒付推进到 under_review，且不可撤回"}}}}}},"responses":{"200":{"description":"证据已暂存或已提交","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"allOf":[{"$ref":"#/components/schemas/DisputeEvidence"}],"type":"object","properties":{"dispute":{"$ref":"#/components/schemas/Dispute"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/disputes/{dispute_no}/accept":{"post":{"tags":["Disputes"],"summary":"接受拒付（认输）","description":"放弃申诉。资金结果与放任举证期过期完全相同，区别只是立刻结案，\n而不是让争议金额一直冻结到截止日。\n\n状态不会立即变成 `lost`——它跟随通道自己的确认，因为那才是真正扣账的时点。","operationId":"acceptDispute","parameters":[{"$ref":"#/components/parameters/DisputeNo"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"已向通道提交接受","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"$ref":"#/components/schemas/Dispute"}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"tags":["Balance"],"summary":"余额查询","description":"当前环境下该币种的钱包余额。","operationId":"retrieveBalance","parameters":[{"name":"currency","in":"query","schema":{"type":"string","enum":["USD","HKD","CNY"],"default":"USD"},"description":"要查询哪个币种的钱包"}],"responses":{"200":{"description":"余额","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","properties":{"merchant_id":{"type":"string","description":"商户号"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"mode":{"enum":["sandbox","live"]},"available_balance":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"账面可用余额，可用于退款；存在未结案拒付时可能为负。（以最小货币单位计，例如美分）"},"withdrawable_balance":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"当前可申请提现金额。正式环境以账面可用余额和上游已清算额度中较小者为准；沙箱按账面可用余额计算。（以最小货币单位计，例如美分）"},"frozen_balance":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"冻结余额：在途退款与未结案拒付占用（以最小货币单位计，例如美分）"},"total_revenue":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计收单金额（以最小货币单位计，例如美分）"},"total_fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计手续费（以最小货币单位计，例如美分）"},"total_payout":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计提现金额（以最小货币单位计，例如美分）"},"total_refund":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计退款金额（以最小货币单位计，例如美分）"},"updated_at":{"type":["string","null"],"format":"date-time","description":"余额最后变动时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance_transactions":{"get":{"tags":["Balance"],"summary":"资金流水","description":"余额是怎么变成现在这样的。手续费、退款、拒付、提现各记一行，加起来就是余额的变化，\n因此比订单列表更适合做每日对账。","operationId":"listBalanceTransactions","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"$ref":"#/components/parameters/Format"},{"name":"type","in":"query","schema":{"enum":["opening_balance","payment_credit","fee_debit","refund_freeze","refund_debit","refund_unfreeze","payout_freeze","payout_unfreeze","payout_success","payout_fee","dispute_freeze","dispute_unfreeze","dispute_debit","dispute_fee","manual_adjustment"]},"description":"只返回该类型的流水"},{"name":"reference_id","in":"query","schema":{"type":"string"},"description":"按关联单号过滤"},{"name":"currency","in":"query","schema":{"type":"string"},"description":"三位 ISO 4217 代码"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"balance_transaction"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BalanceTransaction"}}}}}}},"text/csv":{"schema":{"type":"string"},"example":"带 UTF-8 BOM 的 CSV 文件，金额列已换算成两位小数"}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment_links":{"post":{"tags":["PaymentLinks"],"summary":"创建收款链接","description":"生成一个稳定的收款地址，不写代码也能收款。\n\n返回的 `url` 每被访问一次就生成一笔新订单，因此同一个链接可以收很多笔款。\n公开地址天然会被反复打开，所以按访问者做了每分钟 20 次的限制。","operationId":"createPaymentLink","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"每笔收款金额，必须为正整数（以最小货币单位计，例如美分）"},"currency":{"type":"string","enum":["USD","HKD","CNY"],"default":"USD","description":"币种。沙箱可用全部支持的币种；正式环境仅限平台为你开通的币种"},"subject":{"type":"string","description":"买家在收银台看到的标题"},"max_uses":{"type":["integer","null"],"minimum":1,"description":"可用次数上限，省略为不限"},"expires_at":{"type":["string","null"],"format":"date-time","description":"失效时间，省略为永久有效"},"notify_url":{"type":"string","description":"订单级异步通知地址，必须是公网 HTTPS。正式收款链接可省略，但需有已启用且订阅 payment.succeeded 的正式环境 Webhook 端点。"},"return_url":{"type":"string","description":"支付成功后买家跳回的地址。可包含占位符 {TRADE_NO}、{OUT_TRADE_NO}，跳转时替换为本订单的值；收银台显示支付成功后约 5 秒自动跳转"},"metadata":{"$ref":"#/components/schemas/Metadata"}}}}}},"responses":{"201":{"description":"链接已创建","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"收款链接已创建"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一个可以反复使用的收款地址。每次访问生成一笔新订单再跳转收银台，因此一个链接可以收很多笔款。","properties":{"object":{"const":"payment_link"},"link_id":{"type":"string","description":"链接 id"},"merchant_id":{"type":"string","description":"商户号"},"url":{"type":"string","description":"发给买家的地址，直接打开即可付款"},"mode":{"enum":["sandbox","live"]},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"每笔收款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"subject":{"type":"string","description":"买家在收银台看到的标题"},"status":{"enum":["active","inactive"]},"max_uses":{"type":["integer","null"],"description":"可用次数上限，null 为不限"},"used_count":{"type":"integer","description":"已经生成过多少笔订单"},"expires_at":{"type":["string","null"],"format":"date-time","description":"失效时间"},"notify_url":{"type":["string","null"],"description":"该链接产生订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["PaymentLinks"],"summary":"收款链接列表","description":"按创建时间倒序返回收款链接。","operationId":"listPaymentLinks","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"name":"status","in":"query","schema":{"enum":["active","inactive"]},"description":"只返回该状态的链接"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"payment_link"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment_links/{link_id}":{"get":{"tags":["PaymentLinks"],"summary":"收款链接详情","operationId":"retrievePaymentLink","parameters":[{"name":"link_id","in":"path","required":true,"schema":{"type":"string"},"description":"链接 id"}],"responses":{"200":{"description":"链接详情","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一个可以反复使用的收款地址。每次访问生成一笔新订单再跳转收银台，因此一个链接可以收很多笔款。","properties":{"object":{"const":"payment_link"},"link_id":{"type":"string","description":"链接 id"},"merchant_id":{"type":"string","description":"商户号"},"url":{"type":"string","description":"发给买家的地址，直接打开即可付款"},"mode":{"enum":["sandbox","live"]},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"每笔收款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"subject":{"type":"string","description":"买家在收银台看到的标题"},"status":{"enum":["active","inactive"]},"max_uses":{"type":["integer","null"],"description":"可用次数上限，null 为不限"},"used_count":{"type":"integer","description":"已经生成过多少笔订单"},"expires_at":{"type":["string","null"],"format":"date-time","description":"失效时间"},"notify_url":{"type":["string","null"],"description":"该链接产生订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["PaymentLinks"],"summary":"更新收款链接","description":"可以改标题、可用次数、失效时间、启用状态和 metadata。\n\n**金额与币种不可修改**：已经发出去的链接如果能改金额，买家看到的价格和实际扣款就会对不上。\n需要改价就停用旧链接、新建一个。","operationId":"updatePaymentLink","parameters":[{"name":"link_id","in":"path","required":true,"schema":{"type":"string"},"description":"链接 id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["active","inactive"]},"subject":{"type":"string","description":"买家在收银台看到的标题"},"max_uses":{"type":["integer","null"]},"expires_at":{"type":["string","null"],"format":"date-time"},"metadata":{"$ref":"#/components/schemas/Metadata"}}}}}},"responses":{"200":{"description":"更新后的链接","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"更新成功"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"一个可以反复使用的收款地址。每次访问生成一笔新订单再跳转收银台，因此一个链接可以收很多笔款。","properties":{"object":{"const":"payment_link"},"link_id":{"type":"string","description":"链接 id"},"merchant_id":{"type":"string","description":"商户号"},"url":{"type":"string","description":"发给买家的地址，直接打开即可付款"},"mode":{"enum":["sandbox","live"]},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"每笔收款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"subject":{"type":"string","description":"买家在收银台看到的标题"},"status":{"enum":["active","inactive"]},"max_uses":{"type":["integer","null"],"description":"可用次数上限，null 为不限"},"used_count":{"type":"integer","description":"已经生成过多少笔订单"},"expires_at":{"type":["string","null"],"format":"date-time","description":"失效时间"},"notify_url":{"type":["string","null"],"description":"该链接产生订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoints":{"get":{"tags":["Webhooks"],"summary":"端点列表","description":"当前环境下已配置的端点，最多 5 个，一次返回全部。","operationId":"listWebhookEndpoints","responses":{"200":{"description":"端点列表","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","properties":{"object":{"const":"list"},"resource":{"const":"webhook_endpoint"},"has_more":{"const":false},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhooks"],"summary":"创建端点","description":"注册一个接收事件的地址。\n\n**签名密钥只在这里和轮换接口返回一次。** 它加密存储，之后无法再读回明文——\n这正是它的设计目的：控制台被看到也拿不到密钥。","operationId":"createWebhookEndpoint","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"接收事件的地址。正式环境必须是可公网访问的 HTTPS。"},"description":{"type":"string","description":"备注，便于在控制台区分多个端点"},"enabled_events":{"type":"array","items":{"type":"string"},"description":"订阅的事件类型，省略则为全部"}}}}}},"responses":{"201":{"description":"端点已创建，响应中包含一次性的签名密钥","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"Webhook 端点已创建"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"}],"type":"object","properties":{"secret":{"type":"string","description":"签名密钥，仅此一次返回"},"secret_notice":{"type":"string","description":"提示文案"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoints/{endpoint_id}":{"get":{"tags":["Webhooks"],"summary":"端点详情","operationId":"retrieveWebhookEndpoint","parameters":[{"$ref":"#/components/parameters/EndpointId"}],"responses":{"200":{"description":"端点详情","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhooks"],"summary":"更新端点","description":"可以修改地址、订阅的事件类型和启用状态。\n\n想暂停接收时建议改成 `disabled` 而不是删除：投递历史挂在端点上，\n删掉之后就查不到这段时间漏了什么。","operationId":"updateWebhookEndpoint","parameters":[{"$ref":"#/components/parameters/EndpointId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"新的接收地址"},"description":{"type":["string","null"]},"enabled_events":{"type":"array","items":{"type":"string"}},"status":{"enum":["enabled","disabled"]}}}}}},"responses":{"200":{"description":"更新后的端点","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"更新成功"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"删除端点","operationId":"deleteWebhookEndpoint","parameters":[{"$ref":"#/components/parameters/EndpointId"}],"responses":{"200":{"description":"已删除","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"Webhook 端点已删除"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"}],"type":"object","properties":{"deleted":{"const":true}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoints/{endpoint_id}/rotate_secret":{"post":{"tags":["Webhooks"],"summary":"轮换签名密钥","description":"签发新密钥，旧密钥在 24 小时内继续并行签名。\n\n两个签名会出现在同一个 `X-KukoPay-Signature` 头里（多个 `v1=`），\n所以你可以在窗口期内任意时刻更新配置，不必和平台同步切换。\n只要有任意一个 `v1=` 验签通过，就是合法请求。","operationId":"rotateWebhookEndpointSecret","parameters":[{"$ref":"#/components/parameters/EndpointId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"新的签名密钥","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"签名密钥已轮换"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"}],"type":"object","properties":{"secret":{"type":"string","description":"新的签名密钥，仅此一次返回"},"secret_notice":{"type":"string","description":"提示文案"},"rotation_window_hours":{"type":"number"}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/logs":{"get":{"tags":["Logs"],"summary":"API 调用日志","description":"你自己每一次调用的请求与响应，保留 30 天。\n\n出问题时先查这里：`status=4xx` 过滤出被拒绝的调用，\n或者直接用手上的 `request_id` 定位到那一次请求。\n密钥、卡号一类字段在入库前已被替换成 `[redacted]`。","operationId":"listApiLogs","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"name":"request_id","in":"query","schema":{"type":"string"},"description":"精确定位一次请求"},{"name":"status","in":"query","schema":{"type":"string","example":"4xx"},"description":"精确状态码，或 `4xx` / `5xx` 这样的整类"},{"name":"path","in":"query","schema":{"type":"string"},"description":"按请求路径精确匹配"},{"name":"error_code","in":"query","schema":{"enum":["missing_api_key","invalid_api_key","merchant_not_approved","ip_not_allowed","forbidden","invalid_request","idempotency_error","idempotency_in_progress","order_not_found","refund_not_found","dispute_not_found","event_not_found","payment_link_not_found","endpoint_not_found","default_endpoint_secret_managed","route_not_found","conflict","refund_window_expired","rate_limited","processor_error","internal_error"]},"description":"按错误码过滤"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"api_log"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiLog"}}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"tags":["Events"],"summary":"事件列表","description":"Webhook 的补偿通道。端点挂掉一天、或者压根没配 notify_url，\n都可以从这里把同样的事实补回来，而不用拿自己的订单表跟我们逐条对。","operationId":"listEvents","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"$ref":"#/components/parameters/CreatedGte"},{"$ref":"#/components/parameters/CreatedLte"},{"name":"type","in":"query","schema":{"enum":["payment.succeeded","payment.failed","payment.expired","payment.duplicate_refunded","refund.succeeded","refund.failed","dispute.created","dispute.updated","dispute.won","dispute.lost","dispute.closed"]},"description":"只返回该类型的事件"},{"name":"reference_id","in":"query","schema":{"type":"string"},"description":"按事件主体的单号过滤"}],"responses":{"200":{"description":"一页数据，按创建时间倒序","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","required":["object","resource","has_more","data"],"properties":{"object":{"const":"list"},"resource":{"const":"event"},"has_more":{"type":"boolean","description":"是否还有下一页。不要靠「返回条数 < limit」判断结束。"},"url":{"type":"string","description":"该列表的路径"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{event_id}":{"get":{"tags":["Events"],"summary":"事件查询","description":"收到 Webhook 但当时没能处理完时，用事件 id 从源头重新取一次，而不是信任本地缓存的报文。","operationId":"retrieveEvent","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string"},"description":"事件 id"}],"responses":{"200":{"description":"事件详情","content":{"application/json":{"schema":{"type":"object","required":["code","message","request_id","data"],"properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"message":{"type":"string","description":"给人看的描述，文案可能调整，不要用于逻辑分支","example":"success"},"request_id":{"type":"string","description":"本次请求的唯一标识，与 X-Request-Id 响应头一致","example":"req_9f2c1a7b4e8d0356c1ab77de90f4b215"},"data":{"type":"object","description":"账户上发生的一件事。data.object 与对应 GET 接口返回的对象完全一致，因此一套解析代码即可。","properties":{"object":{"const":"event"},"id":{"type":"string","description":"事件 id","example":"evt_3f1c..."},"type":{"enum":["payment.succeeded","payment.failed","payment.expired","payment.duplicate_refunded","refund.succeeded","refund.failed","dispute.created","dispute.updated","dispute.won","dispute.lost","dispute.closed"],"description":"事件类型"},"mode":{"enum":["sandbox","live"]},"created_at":{"type":"string","format":"date-time","description":"事件发生时间"},"data":{"type":"object","required":["object"],"properties":{"object":{"description":"事件主体，结构取决于 type","oneOf":[{"$ref":"#/components/schemas/Order"},{"$ref":"#/components/schemas/Refund"},{"$ref":"#/components/schemas/Dispute"}]}}}}}}}}}},"400":{"description":"invalid_request — 参数不合法，param 指出具体字段\nidempotency_error — 同一个 Idempotency-Key 被用于了内容不同的请求\nrefund_window_expired — 订单的支付方式有退款期限且已超过，常见于支付宝、微信支付等钱包","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_api_key — 请求未携带 X-Api-Key 头\ninvalid_api_key — 密钥无效，或已在控制台被重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_not_approved — 用正式密钥调用，但资质尚未审核通过\nip_not_allowed — 请求来源 IP 不在该商户配置的 IP 白名单内\nforbidden — 该对象不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"order_not_found — 订单不存在，或不属于当前商户 / 当前环境\nrefund_not_found — 退款单不存在，或不属于当前商户 / 当前环境\ndispute_not_found — 拒付记录不存在，或不属于当前商户 / 当前环境\nevent_not_found — 事件不存在，或不属于当前商户 / 当前环境\npayment_link_not_found — 收款链接不存在，或不属于当前商户 / 当前环境\nendpoint_not_found — Webhook 端点不存在，或不属于当前商户\nroute_not_found — 请求的路径不是任何 API 接口","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress — 该 Idempotency-Key 的首次请求仍在处理中\ndefault_endpoint_secret_managed — 开发者中心默认回调端点与订单级 notify_url 共用签名密钥，不能单独轮换\nconflict — 对象状态已变化，订单存在未结案拒付，或相同商户订单号对应的下单内容不同","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited — 超出该接口的每分钟调用配额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error — 平台内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"processor_error — 上游渠道异常，本地资金未被修改","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"商户密钥。前缀决定环境：`kuko_test_` 为沙箱，`kuko_live_` 为正式。\n正式密钥在资质审核通过前调用会返回 `merchant_not_approved`。"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"传输级幂等键，建议用 UUID v4。平台会存下首次的响应并在 24 小时内原样重放，\n命中重放时带 `Idempotent-Replayed: true` 响应头。\n同一个 Key 配不同的请求体会返回 `idempotency_error`。"},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"每页条数"},"StartingAfter":{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"上一页最后一个对象的 id，用于翻到下一页"},"EndingBefore":{"name":"ending_before","in":"query","schema":{"type":"string"},"description":"当前页第一个对象的 id，用于往回翻。不能与 starting_after 同时使用。"},"CreatedGte":{"name":"created[gte]","in":"query","schema":{"type":"string"},"description":"只返回该时刻之后创建的对象。接受 ISO-8601 或 Unix 秒。"},"CreatedLte":{"name":"created[lte]","in":"query","schema":{"type":"string"},"description":"只返回该时刻之前创建的对象"},"DisputeNo":{"name":"dispute_no","in":"path","required":true,"schema":{"type":"string"},"description":"平台拒付号或上游渠道拒付号"},"EndpointId":{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook 端点 id"},"Format":{"name":"format","in":"query","schema":{"enum":["csv"]},"description":"传 `csv` 时返回带 UTF-8 BOM 的 CSV 文件，单次最多 10,000 行。\n导出单独计频率额度（每分钟 10 次），且分页参数不生效。"}},"schemas":{"Order":{"type":"object","description":"一笔支付订单。收银台、查询接口与 payment.* 事件返回的是同一个结构。","properties":{"object":{"const":"order"},"trade_no":{"type":"string","description":"平台交易号。沙箱以 TRD_SB_ 开头，正式以 TRD_ 开头。"},"out_trade_no":{"type":"string","description":"商户自己的订单号，在同一商户同一环境下唯一"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"订单金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"平台收单手续费，入账后才有值（以最小货币单位计，例如美分）"},"net_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"实际入账净额 = amount - fee（以最小货币单位计，例如美分）"},"refunded_amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"已退款总额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码","example":"USD"},"subject":{"type":"string","description":"商品标题"},"status":{"enum":["pending","paid","partially_refunded","refunded","failed","expired"],"description":"订单状态"},"mode":{"enum":["sandbox","live"],"description":"由调用所用的密钥决定，不接受请求体指定"},"payment_id":{"type":["string","null"],"description":"当前关联的上游渠道支付号。买家更换支付方式后会变化，对账请以 trade_no 为准"},"payment_method":{"type":["string","null"],"enum":["card","alipay","wechat_pay","apple_pay","google_pay",null],"description":"买家实际使用的支付方式，支付成功后才有值"},"refundable_until":{"type":["string","null"],"format":"date-time","description":"最晚可退款时间。仅部分支付方式有期限（如支付宝、微信支付），无期限为 null"},"checkout_url":{"type":"string","description":"托管收银台地址。已签名且会过期，不要长期缓存。"},"expires_at":{"type":"string","format":"date-time","description":"收银台链接失效时间。此后买家无法再发起支付，未支付的订单由平台关闭为 expired"},"notify_url":{"type":["string","null"],"description":"该订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"paid_at":{"type":["string","null"],"format":"date-time","description":"支付成功时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"}}},"Refund":{"type":"object","description":"一笔退款。查询接口与 refund.* 事件返回的是同一个结构。","properties":{"object":{"const":"refund"},"refund_no":{"type":"string","description":"平台退款号"},"out_refund_no":{"type":["string","null"],"description":"商户自己的退款号"},"processor_refund_id":{"type":["string","null"],"description":"上游渠道退款号"},"trade_no":{"type":"string","description":"原交易号"},"out_trade_no":{"type":["string","null"],"description":"原订单的商户订单号"},"merchant_id":{"type":"string","description":"商户号"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"本次退款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"reason":{"type":["string","null"],"description":"退款原因"},"status":{"enum":["pending","succeeded","failed"],"description":"退款状态"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"通道已受理但尚未确认时为 true：该金额已从可用余额转入冻结，尚未真实扣账。"},"error_message":{"type":["string","null"],"description":"失败原因"},"order_status":{"type":["string","null"],"description":"原订单当前状态"},"order_amount":{"type":["integer","null"],"description":"原订单金额"},"refunded_amount":{"type":["integer","null"],"description":"该订单已退总额"},"remaining_amount":{"type":["integer","null"],"description":"该订单剩余可退金额"},"metadata":{"$ref":"#/components/schemas/Metadata"},"settled_at":{"type":["string","null"],"format":"date-time","description":"退款真实完成时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}},"Dispute":{"type":"object","description":"一笔拒付（Chargeback）。开案时争议金额从可用余额转入冻结，结案时要么释放要么真实扣账。","properties":{"object":{"const":"dispute"},"dispute_no":{"type":"string","description":"平台拒付号"},"trade_no":{"type":"string","description":"被拒付的交易号"},"merchant_id":{"type":"string","description":"商户号"},"processor_dispute_id":{"type":"string","description":"上游渠道的拒付号，可与收单机构后台核对"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"争议金额（以最小货币单位计，例如美分）"},"fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"拒付处理费，败诉后才有值（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"status":{"enum":["needs_response","under_review","won","lost","closed"],"description":"拒付状态"},"processor_status":{"type":["string","null"],"description":"上游渠道的原始状态"},"reason":{"type":["string","null"],"description":"发卡行给出的拒付原因"},"mode":{"enum":["sandbox","live"]},"funds_frozen":{"type":"boolean","description":"争议金额是否仍在冻结中"},"evidence_due_by":{"type":["string","null"],"format":"date-time","description":"举证截止时间"},"opened_at":{"type":"string","format":"date-time","description":"开案时间"},"closed_at":{"type":["string","null"],"format":"date-time","description":"结案时间"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}},"BalanceTransaction":{"type":"object","description":"一条余额变动流水。所有类型的金额加总即为余额的变化，是做对账最合适的口径。","properties":{"object":{"const":"balance_transaction"},"id":{"type":"string","description":"流水号，也是分页游标"},"merchant_id":{"type":"string","description":"商户号"},"type":{"enum":["opening_balance","payment_credit","fee_debit","refund_freeze","refund_debit","refund_unfreeze","payout_freeze","payout_unfreeze","payout_success","payout_fee","dispute_freeze","dispute_unfreeze","dispute_debit","dispute_fee","manual_adjustment"],"description":"变动类型"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"变动金额，支出为负（以最小货币单位计，例如美分）"},"balance_before":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"变动前可用余额（以最小货币单位计，例如美分）"},"balance_after":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"变动后可用余额（以最小货币单位计，例如美分）"},"reference_id":{"type":"string","description":"触发这笔流水的订单号 / 退款号 / 拒付号 / 提现号"},"description":{"type":"string","description":"说明"},"mode":{"enum":["sandbox","live"]},"created_at":{"type":"string","format":"date-time","description":"发生时间"}}},"Balance":{"type":"object","properties":{"merchant_id":{"type":"string","description":"商户号"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"mode":{"enum":["sandbox","live"]},"available_balance":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"账面可用余额，可用于退款；存在未结案拒付时可能为负。（以最小货币单位计，例如美分）"},"withdrawable_balance":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"当前可申请提现金额。正式环境以账面可用余额和上游已清算额度中较小者为准；沙箱按账面可用余额计算。（以最小货币单位计，例如美分）"},"frozen_balance":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"冻结余额：在途退款与未结案拒付占用（以最小货币单位计，例如美分）"},"total_revenue":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计收单金额（以最小货币单位计，例如美分）"},"total_fee":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计手续费（以最小货币单位计，例如美分）"},"total_payout":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计提现金额（以最小货币单位计，例如美分）"},"total_refund":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"累计退款金额（以最小货币单位计，例如美分）"},"updated_at":{"type":["string","null"],"format":"date-time","description":"余额最后变动时间"}}},"Event":{"type":"object","description":"账户上发生的一件事。data.object 与对应 GET 接口返回的对象完全一致，因此一套解析代码即可。","properties":{"object":{"const":"event"},"id":{"type":"string","description":"事件 id","example":"evt_3f1c..."},"type":{"enum":["payment.succeeded","payment.failed","payment.expired","payment.duplicate_refunded","refund.succeeded","refund.failed","dispute.created","dispute.updated","dispute.won","dispute.lost","dispute.closed"],"description":"事件类型"},"mode":{"enum":["sandbox","live"]},"created_at":{"type":"string","format":"date-time","description":"事件发生时间"},"data":{"type":"object","required":["object"],"properties":{"object":{"description":"事件主体，结构取决于 type","oneOf":[{"$ref":"#/components/schemas/Order"},{"$ref":"#/components/schemas/Refund"},{"$ref":"#/components/schemas/Dispute"}]}}}}},"ApiLog":{"type":"object","description":"你自己调用本 API 的记录，保留 30 天。请求体与响应体在入库前已做脱敏，可以直接发给我们排障。","properties":{"object":{"const":"api_log"},"request_id":{"type":"string","description":"该次请求的唯一标识，也是分页游标"},"merchant_id":{"type":"string","description":"商户号"},"mode":{"enum":["sandbox","live"]},"method":{"type":"string","description":"HTTP 方法"},"path":{"type":"string","description":"请求路径"},"status":{"type":"integer","description":"HTTP 状态码"},"error_code":{"type":["string","null"],"description":"失败时的 error 字段"},"duration_ms":{"type":"integer","description":"服务端处理耗时"},"ip":{"type":["string","null"],"description":"来源 IP"},"user_agent":{"type":["string","null"]},"idempotency_key":{"type":["string","null"]},"request_body":{"description":"脱敏后的请求体"},"response_body":{"description":"脱敏后的响应体"},"created_at":{"type":"string","format":"date-time","description":"发生时间"}}},"DisputeEvidence":{"type":"object","description":"你为反驳拒付提交的材料。证据本身保存在支付通道侧——发卡行只看得到通道持有的内容；这里是平台的记录。","properties":{"object":{"const":"dispute_evidence"},"dispute_no":{"type":"string","description":"拒付号"},"evidence":{"type":"object","description":"文字材料。可用字段：product_description / customer_name / customer_email_address / customer_purchase_ip / billing_address / shipping_address / shipping_carrier / shipping_tracking_number / shipping_date / service_date / access_activity_log / refund_policy_disclosure / refund_refusal_explanation / cancellation_policy_disclosure / cancellation_rebuttal","additionalProperties":{"type":"string"}},"files":{"type":"array","description":"已上传到通道的证据文件","items":{"type":"object","properties":{"type":{"enum":["receipt","customer_communication","customer_signature","shipping_documentation","service_documentation","cancellation_policy","refund_policy","invoice_showing_distinct_transactions","recurring_transaction_agreement","uncategorized_file"]},"channel_file_id":{"type":"string","description":"通道侧的文件 id"},"file_name":{"type":"string","description":"文件名"},"byte_size":{"type":"integer"}}}},"submitted":{"type":"boolean","description":"false 表示仍是草稿，尚未发给发卡行"},"submitted_at":{"type":["string","null"],"format":"date-time","description":"提交时间"},"updated_at":{"type":["string","null"],"format":"date-time","description":"最后修改时间"}}},"PaymentLink":{"type":"object","description":"一个可以反复使用的收款地址。每次访问生成一笔新订单再跳转收银台，因此一个链接可以收很多笔款。","properties":{"object":{"const":"payment_link"},"link_id":{"type":"string","description":"链接 id"},"merchant_id":{"type":"string","description":"商户号"},"url":{"type":"string","description":"发给买家的地址，直接打开即可付款"},"mode":{"enum":["sandbox","live"]},"amount":{"type":"integer","format":"int64","minimum":-9007199254740991,"maximum":9007199254740991,"description":"每笔收款金额（以最小货币单位计，例如美分）"},"currency":{"type":"string","description":"三位 ISO 4217 代码"},"subject":{"type":"string","description":"买家在收银台看到的标题"},"status":{"enum":["active","inactive"]},"max_uses":{"type":["integer","null"],"description":"可用次数上限，null 为不限"},"used_count":{"type":"integer","description":"已经生成过多少笔订单"},"expires_at":{"type":["string","null"],"format":"date-time","description":"失效时间"},"notify_url":{"type":["string","null"],"description":"该链接产生订单的异步通知地址"},"return_url":{"type":["string","null"],"description":"支付完成后买家跳回的地址"},"metadata":{"$ref":"#/components/schemas/Metadata"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}},"WebhookEndpoint":{"type":"object","description":"一个接收事件的地址。端点按环境隔离，沙箱端点永远收不到正式事件。","properties":{"object":{"const":"webhook_endpoint"},"endpoint_id":{"type":"string","description":"端点 id"},"merchant_id":{"type":"string","description":"商户号"},"mode":{"enum":["sandbox","live"]},"url":{"type":"string","description":"接收事件的 HTTPS 地址"},"description":{"type":["string","null"],"description":"备注"},"enabled_events":{"type":"array","items":{"type":"string"},"description":"订阅的事件类型。`[\"*\"]` 表示全部，并且会自动包含之后新增的类型。\n可选值：payment.succeeded / payment.failed / payment.expired / payment.duplicate_refunded / refund.succeeded / refund.failed / dispute.created / dispute.updated / dispute.won / dispute.lost / dispute.closed"},"status":{"enum":["enabled","disabled"]},"previous_secret_active_until":{"type":["string","null"],"format":"date-time","description":"轮换窗口内旧密钥仍会签名，到这个时刻为止"},"created_at":{"type":"string","format":"date-time","description":"创建时间"},"updated_at":{"type":"string","format":"date-time","description":"更新时间"}}},"Metadata":{"type":"object","description":"你自己挂在该对象上的键值数据，用来关联业务系统里的 id，\n最多 50 个键，键不超过 40 字符，值不超过 500 字符。\n键和值都必须是字符串——这是有意的限制：嵌套结构会变成一份我们必须永远兼容的隐式 schema。","additionalProperties":{"type":"string","maxLength":500},"example":{"customer_id":"cus_42","order_source":"shopify"}},"Error":{"type":"object","required":["code","error","type","message","doc_url","request_id"],"description":"所有接口共用的错误结构。\n请基于 error 做逻辑分支；message 的文案可能调整。\ntype 是粗粒度分类，新增 error 时不会变化。","properties":{"code":{"type":"integer","description":"与 HTTP 状态码一致"},"error":{"enum":["missing_api_key","invalid_api_key","merchant_not_approved","ip_not_allowed","forbidden","invalid_request","idempotency_error","idempotency_in_progress","order_not_found","refund_not_found","dispute_not_found","event_not_found","payment_link_not_found","endpoint_not_found","default_endpoint_secret_managed","route_not_found","conflict","refund_window_expired","rate_limited","processor_error","internal_error"],"description":"稳定的机器可读错误标识"},"type":{"enum":["authentication_error","permission_error","invalid_request_error","idempotency_error","rate_limit_error","api_connection_error","api_error"],"description":"authentication_error: 密钥缺失或无效，请求没有被识别为任何商户; permission_error: 身份成立，但当前商户无权执行该操作; invalid_request_error: 请求本身不合法：参数错误、对象不存在、状态冲突; idempotency_error: 同一个幂等键被用于了不同的请求内容; rate_limit_error: 触发调用频率限制; api_connection_error: 上游渠道异常，本地资金未被修改; api_error: 平台内部错误"},"message":{"type":"string","description":"给人看的描述"},"param":{"type":["string","null"],"description":"出错的请求字段名"},"doc_url":{"type":"string","description":"指向该错误码的文档锚点"},"request_id":{"type":"string","description":"本次请求的唯一标识，反馈问题时请附上"}}}}},"x-rate-limits":{"description":"按商户维度的每分钟配额，窗口为一分钟的固定窗口。","write":120,"read":600,"export":10},"x-webhook-events":[{"type":"payment.succeeded","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"payment.failed","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"payment.expired","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"payment.duplicate_refunded","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"refund.succeeded","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"refund.failed","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"dispute.created","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"dispute.updated","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"dispute.won","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"dispute.lost","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"},{"type":"dispute.closed","description":"事件体中的 data.object 与对应 GET 接口返回的对象完全一致。"}]}