cdnca

开放接口

/v1/admin/recharge-payments

3 个接口

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

方法路径摘要认证
POST/v1/admin/recharge-payments/orders/{order_id}/reconciliation向支付渠道查询并应用确定状态登录会话
POST/v1/admin/recharge-payments/orders/{order_id}/refunds执行已批准的退款（意图先持久化，按稳定退款单号外调，结果事务化入账）登录会话
POST/v1/admin/recharge-payments/orders/{order_id}/voids执行已批准的撤销（意图先持久化，按稳定退款单号外调，结果事务化入账）登录会话

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

接口详情

POST /v1/admin/recharge-payments/orders/{order_id}/reconciliation

向支付渠道查询并应用确定状态

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

全部需要：billing.recharges.reconcile

参数

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

请求体

application/json · 必填：是

reconcileRechargePayment 请求体
名称类型必填说明
tenant_scope_idstring(uuid)是—
providerstring: alipay / wechat是—
expected_revisioninteger(int64)是—

响应

reconcileRechargePayment 响应
状态码说明
200确定结果、仍需对账或精确重放

字段：order_id: string(uuid) state: string: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required reason_code: string revision: integer(int64) transaction_id?: string(uuid) replayed: boolean deferred: boolean

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

失败时怎么办

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

↑ 回到列表

POST /v1/admin/recharge-payments/orders/{order_id}/refunds

执行已批准的退款（意图先持久化，按稳定退款单号外调，结果事务化入账）

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

全部需要：billing.recharges.compensate

参数

requestRechargePaymentRefund 参数
名称位置类型必填说明
order_idpathstring(uuid)是—
X-Request-IDheaderstring是—
Idempotency-Keyheaderstring是—
X-Step-Up-Tokenheaderstring否首次执行必填；恢复已持久化的同一退款/撤销意图（同审批）时省略

请求体

application/json · 必填：是

requestRechargePaymentRefund 请求体
名称类型必填说明
approval_idstring(uuid)是—
tenant_scope_idstring(uuid)是—
amount_minorinteger(int64)是—
expected_revisioninteger(int64)是—

响应

requestRechargePaymentRefund 响应
状态码说明
200渠道结果已确定：succeeded（渠道已确认且已入账）或 failed（渠道未接受，资金未退出、预留已释放）

字段：compensation_id: string(uuid) approval_id: string(uuid) order_id: string(uuid) tenant_scope_id: string(uuid) kind: string: refund / void amount_minor: integer(int64) currency: string status: string: pending / succeeded / failed / unknown reason_code: string attempt: integer(int64) provider_request_id: string order_state: string: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required order_revision: integer(int64) retryable: boolean replayed: boolean

202退款意图已持久化但渠道结果待确认（pending/unknown）；用同一请求（同 Idempotency-Key，或同审批，无需新的 X-Step-Up-Token）重试会查询原退款单号，不会重复退款

字段：compensation_id: string(uuid) approval_id: string(uuid) order_id: string(uuid) tenant_scope_id: string(uuid) kind: string: refund / void amount_minor: integer(int64) currency: string status: string: pending / succeeded / failed / unknown reason_code: string attempt: integer(int64) provider_request_id: string order_state: string: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required order_revision: integer(int64) retryable: boolean replayed: boolean

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

失败时怎么办

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

↑ 回到列表

POST /v1/admin/recharge-payments/orders/{order_id}/voids

执行已批准的撤销（意图先持久化，按稳定退款单号外调，结果事务化入账）

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

全部需要：billing.recharges.compensate

参数

requestRechargePaymentVoid 参数
名称位置类型必填说明
order_idpathstring(uuid)是—
X-Request-IDheaderstring是—
Idempotency-Keyheaderstring是—
X-Step-Up-Tokenheaderstring否首次执行必填；恢复已持久化的同一退款/撤销意图（同审批）时省略

请求体

application/json · 必填：是

requestRechargePaymentVoid 请求体
名称类型必填说明
approval_idstring(uuid)是—
tenant_scope_idstring(uuid)是—
amount_minorinteger(int64)是—
expected_revisioninteger(int64)是—

响应

requestRechargePaymentVoid 响应
状态码说明
200渠道结果已确定：succeeded（渠道已确认且已入账）或 failed（渠道未接受，资金未退出、预留已释放）

字段：compensation_id: string(uuid) approval_id: string(uuid) order_id: string(uuid) tenant_scope_id: string(uuid) kind: string: refund / void amount_minor: integer(int64) currency: string status: string: pending / succeeded / failed / unknown reason_code: string attempt: integer(int64) provider_request_id: string order_state: string: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required order_revision: integer(int64) retryable: boolean replayed: boolean

202撤销意图已持久化但渠道结果待确认（pending/unknown）；用同一请求（同 Idempotency-Key，或同审批，无需新的 X-Step-Up-Token）重试会查询原退款单号，不会重复撤销

字段：compensation_id: string(uuid) approval_id: string(uuid) order_id: string(uuid) tenant_scope_id: string(uuid) kind: string: refund / void amount_minor: integer(int64) currency: string status: string: pending / succeeded / failed / unknown reason_code: string attempt: integer(int64) provider_request_id: string order_state: string: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required order_revision: integer(int64) retryable: boolean replayed: boolean

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

失败时怎么办

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

↑ 回到列表