cdnca

开放接口

/v1/recharge-payments

3 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
POST/v1/recharge-payments/checkouts为已认证租户充值订单创建签名收银台登录会话
POST/v1/recharge-payments/orders/{order_id}/cancellation取消当前租户自己的待支付充值订单登录会话
GET/v1/recharge-payments/orders/{order_id}/usdt租户 USDT 收银台状态（确认进度、到账、人工复核），只读登录会话

契约文件：api/control-recharge-payments.openapi.yaml

接口详情

POST /v1/recharge-payments/checkouts

为已认证租户充值订单创建签名收银台

operationId
createRechargePaymentCheckout
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：billing.recharges.create

参数

createRechargePaymentCheckout 参数
名称位置类型必填说明
X-Request-IDheaderstring是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createRechargePaymentCheckout 请求体
名称类型必填说明
order_idstring(uuid)是—
providerstring: alipay / wechat / usdt是—
networkstring: tron / bsc / polygon / ethereum否USDT only; omitted uses the first offered network (TRC20 when offered).
expected_revisioninteger(int64)是—

响应

createRechargePaymentCheckout 响应
状态码说明
201新建或精确幂等重放；不返回原始签名载荷

字段：provider: string: alipay / wechat / usdt provider_account_id: string order_id: string(uuid) tenant_scope_id: string(uuid) amount_minor: integer(int64) currency: string expires_at: string(date-time) verification_key_id: string payload_sha256: string signature_sha256: string checkout_url: string crypto?: CryptoCheckout replayed: boolean

400稳定错误码；message 禁止直接展示给用户
401稳定错误码；message 禁止直接展示给用户
403稳定错误码；message 禁止直接展示给用户
409稳定错误码；message 禁止直接展示给用户
503渠道不可用或结果不确定；调用方不得自行推断支付结果

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/recharge-payments/orders/{order_id}/cancellation

取消当前租户自己的待支付充值订单

operationId
cancelRechargePayment
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：billing.recharges.cancel

说明（契约原文）

在调用支付渠道前先持久化不可变请求身份。渠道超时或响应丢失返回 unknown，调用方必须使用 相同 Idempotency-Key 和 X-Request-ID 重试；服务端复用相同 provider_request_id。

参数

cancelRechargePayment 参数
名称位置类型必填说明
order_idpathstring(uuid)是—
X-Request-IDheaderstring是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

cancelRechargePayment 请求体
名称类型必填说明
expected_revisioninteger(int64)是—

响应

cancelRechargePayment 响应
状态码说明
200渠道已确定关闭或已确定拒绝

字段：cancellation_id: string(uuid) order_id: string(uuid) status: string: pending / succeeded / failed / unknown order_state: string: pending / paid / failed / canceled order_revision: integer(int64) attempt: integer(int64) provider_request_id: string reason_code: string retryable: boolean replayed: boolean

202已持久化请求，但渠道结果仍为 pending 或 unknown

字段：cancellation_id: string(uuid) order_id: string(uuid) status: string: pending / succeeded / failed / unknown order_state: string: pending / paid / failed / canceled order_revision: integer(int64) attempt: integer(int64) provider_request_id: string reason_code: string retryable: boolean replayed: boolean

400稳定错误码；message 禁止直接展示给用户
401稳定错误码；message 禁止直接展示给用户
403稳定错误码；message 禁止直接展示给用户
409稳定错误码；message 禁止直接展示给用户
503渠道不可用或结果不确定；调用方不得自行推断支付结果

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/recharge-payments/orders/{order_id}/usdt

租户 USDT 收银台状态（确认进度、到账、人工复核），只读

operationId
getRechargeUSDTStatus
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：billing.recharges.create

参数

getRechargeUSDTStatus 参数
名称位置类型必填说明
order_idpathstring(uuid)是—

响应

getRechargeUSDTStatus 响应
状态码说明
200本人订单最新一张 USDT 发票的状态

字段：order_id: string(uuid) order_state: string network: string: tron / bsc / polygon / ethereum address: string token_contract: string token_amount: string token_decimals: integer received: string fiat_minor: integer(int64) rate: string markup_bp: integer expires_at: string(date-time) stage: string: awaiting_payment / detected / confirming / credited / expired / review confirmations: integer required_confirmations: integer review_required: boolean review_kinds: array<string>

400稳定错误码；message 禁止直接展示给用户
401稳定错误码；message 禁止直接展示给用户
403稳定错误码；message 禁止直接展示给用户
404稳定错误码；message 禁止直接展示给用户
503稳定错误码；message 禁止直接展示给用户

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表