Operation details
POST /v1/admin/recharge-payments/orders/{order_id}/reconciliation
向支付渠道查询并应用确定状态
- operationId
reconcileRechargePayment- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：billing.recharges.reconcile
Parameters
reconcileRechargePayment Parameters| Name | In | Type | Required | Description |
|---|
order_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
reconcileRechargePayment Request body| Name | Type | Required | Description |
|---|
tenant_scope_id | string(uuid) | Yes | — |
|---|
provider | string: alipay / wechat | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
reconcileRechargePayment Responses| Status | Description |
|---|
200 | 确定结果、仍需对账或精确重放 Fields：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 | 渠道不可用或结果不确定；调用方不得自行推断支付结果 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/recharge-payments/orders/{order_id}/refunds
执行已批准的退款（意图先持久化，按稳定退款单号外调，结果事务化入账）
- operationId
requestRechargePaymentRefund- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：billing.recharges.compensate
Parameters
requestRechargePaymentRefund Parameters| Name | In | Type | Required | Description |
|---|
order_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Step-Up-Token | header | string | No | 首次执行必填；恢复已持久化的同一退款/撤销意图（同审批）时省略 |
|---|
Request body
application/json · Required：Yes
requestRechargePaymentRefund Request body| Name | Type | Required | Description |
|---|
approval_id | string(uuid) | Yes | — |
|---|
tenant_scope_id | string(uuid) | Yes | — |
|---|
amount_minor | integer(int64) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
requestRechargePaymentRefund Responses| Status | Description |
|---|
200 | 渠道结果已确定：succeeded（渠道已确认且已入账）或 failed（渠道未接受，资金未退出、预留已释放） Fields：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）重试会查询原退款单号，不会重复退款 Fields：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 | 渠道不可用或结果不确定；调用方不得自行推断支付结果 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/recharge-payments/orders/{order_id}/voids
执行已批准的撤销（意图先持久化，按稳定退款单号外调，结果事务化入账）
- operationId
requestRechargePaymentVoid- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：billing.recharges.compensate
Parameters
requestRechargePaymentVoid Parameters| Name | In | Type | Required | Description |
|---|
order_id | path | string(uuid) | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Step-Up-Token | header | string | No | 首次执行必填；恢复已持久化的同一退款/撤销意图（同审批）时省略 |
|---|
Request body
application/json · Required：Yes
requestRechargePaymentVoid Request body| Name | Type | Required | Description |
|---|
approval_id | string(uuid) | Yes | — |
|---|
tenant_scope_id | string(uuid) | Yes | — |
|---|
amount_minor | integer(int64) | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
requestRechargePaymentVoid Responses| Status | Description |
|---|
200 | 渠道结果已确定：succeeded（渠道已确认且已入账）或 failed（渠道未接受，资金未退出、预留已释放） Fields：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）重试会查询原退款单号，不会重复撤销 Fields：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 | 渠道不可用或结果不确定；调用方不得自行推断支付结果 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list