cdnca

API reference

/v1/recharges

3 operations

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

MethodPathSummaryAuth
GET/v1/recharges/ordersList recharge orders owned by the authenticated tenant userSession
POST/v1/recharges/ordersCreate an authenticated tenant recharge orderSession
GET/v1/recharges/policyRead the effective platform recharge policy for an authenticated tenantSession

Contract file：api/control-recharges.openapi.yaml

Operation details

GET /v1/recharges/orders

List recharge orders owned by the authenticated tenant user

operationId
listOwnRechargeOrders
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

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

listOwnRechargeOrders Parameters
NameInTypeRequiredDescription
X-Request-IDheaderstringYes—
pagequeryintegerNo—
limitqueryintegerNo—
channelquerystring: alipay / wechat / transfer / usdtNo—
statequerystring: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_requiredNo—
fromquerystring(date-time)No—
toquerystring(date-time)No—
snapshot_atquerystring(date-time)NoReuse snapshot_at returned by the first page to keep later pages and CSV on the same fact boundary.

Responses

listOwnRechargeOrders Responses
StatusDescription
200Stable database snapshot

Fields：items: array<RechargeOrder> total: integer(int64) page: integer limit: integer snapshot_at: string(date-time)

400Stable error code; message is not safe for direct UI rendering
401Stable error code; message is not safe for direct UI rendering
403Stable error code; message is not safe for direct UI rendering

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.

↑ Back to list

POST /v1/recharges/orders

Create an authenticated tenant recharge order

operationId
createRechargeOrder
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.account.read billing.recharges.create

Parameters

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

Request body

application/json · Required：Yes

createRechargeOrder Request body
NameTypeRequiredDescription
channelstring: alipay / wechat / transfer / usdtYes—
amount_minorinteger(int64)Yes—

Responses

createRechargeOrder Responses
StatusDescription
201Created or exact replay

Fields：id: string(uuid) display_id: string tenant_scope_id: string(uuid) tenant_id: string(uuid) user_id: string(uuid) user_display_id: string channel: string: alipay / wechat / transfer / usdt provider: string amount_minor: integer(int64) captured_minor: integer(int64) refunded_minor: integer(int64) net_minor: integer(int64) currency: string state: string: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required revision: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Stable error code; message is not safe for direct UI rendering
401Stable error code; message is not safe for direct UI rendering
403Stable error code; message is not safe for direct UI rendering
409Stable error code; message is not safe for direct UI rendering

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.

↑ Back to list

GET /v1/recharges/policy

Read the effective platform recharge policy for an authenticated tenant

operationId
getRechargePolicy
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.account.read billing.recharges.create

Description (from the contract)

Requires billing.recharges.create on the caller's current active tenant session. The response contains only non-sensitive payment availability, default selection and verification restriction fields. Order creation and provider checkout re-read and lock the same policy, so this projection cannot bypass a concurrent administrator change.

Parameters

getRechargePolicy Parameters
NameInTypeRequiredDescription
X-Request-IDheaderstringYes—

Responses

getRechargePolicy Responses
StatusDescription
200Current platform recharge policy

Fields：wechat_payment_enabled: boolean alipay_payment_enabled: boolean bank_transfer_enabled: boolean usdt_payment_enabled: boolean default_recharge_method: string: none / wechat / alipay / bank_transfer / usdt recharge_restriction: string: none / individual_verified / enterprise_verified available_methods: array<string: wechat / alipay / usdt / bank_transfer> usdt_networks?: array<string: tron / bsc / polygon / ethereum>

400Stable error code; message is not safe for direct UI rendering
401Stable error code; message is not safe for direct UI rendering
403Stable error code; message is not safe for direct UI rendering
503Stable error code; message is not safe for direct UI rendering

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.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list