cdnca

API reference

/v1/recharge-payments

3 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

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

Contract file：api/control-recharge-payments.openapi.yaml

Operation details

POST /v1/recharge-payments/checkouts

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

operationId
createRechargePaymentCheckout
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.create

Parameters

createRechargePaymentCheckout Parameters
NameInTypeRequiredDescription
X-Request-IDheaderstringYes—
Idempotency-KeyheaderstringYes—

Request body

application/json · Required：Yes

createRechargePaymentCheckout Request body
NameTypeRequiredDescription
order_idstring(uuid)Yes—
providerstring: alipay / wechat / usdtYes—
networkstring: tron / bsc / polygon / ethereumNoUSDT only; omitted uses the first offered network (TRC20 when offered).
expected_revisioninteger(int64)Yes—

Responses

createRechargePaymentCheckout Responses
StatusDescription
201新建或精确幂等重放；不返回原始签名载荷

Fields：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渠道不可用或结果不确定；调用方不得自行推断支付结果

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/recharge-payments/orders/{order_id}/cancellation

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

operationId
cancelRechargePayment
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.cancel

Description (from the contract)

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

Parameters

cancelRechargePayment Parameters
NameInTypeRequiredDescription
order_idpathstring(uuid)Yes—
X-Request-IDheaderstringYes—
Idempotency-KeyheaderstringYes—

Request body

application/json · Required：Yes

cancelRechargePayment Request body
NameTypeRequiredDescription
expected_revisioninteger(int64)Yes—

Responses

cancelRechargePayment Responses
StatusDescription
200渠道已确定关闭或已确定拒绝

Fields：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

Fields：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渠道不可用或结果不确定；调用方不得自行推断支付结果

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

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

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

operationId
getRechargeUSDTStatus
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.create

Parameters

getRechargeUSDTStatus Parameters
NameInTypeRequiredDescription
order_idpathstring(uuid)Yes—

Responses

getRechargeUSDTStatus Responses
StatusDescription
200本人订单最新一张 USDT 发票的状态

Fields：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 禁止直接展示给用户

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.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list