cdnca

开放接口

/v1/recharges

3 个接口

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

方法路径摘要认证
GET/v1/recharges/ordersList recharge orders owned by the authenticated tenant user登录会话
POST/v1/recharges/ordersCreate an authenticated tenant recharge order登录会话
GET/v1/recharges/policyRead the effective platform recharge policy for an authenticated tenant登录会话

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

接口详情

GET /v1/recharges/orders

List recharge orders owned by the authenticated tenant user

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

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

listOwnRechargeOrders 参数
名称位置类型必填说明
X-Request-IDheaderstring是—
pagequeryinteger否—
limitqueryinteger否—
channelquerystring: alipay / wechat / transfer / usdt否—
statequerystring: pending / paid / partially_refunded / refunded / voided / failed / canceled / reconcile_required否—
fromquerystring(date-time)否—
toquerystring(date-time)否—
snapshot_atquerystring(date-time)否Reuse snapshot_at returned by the first page to keep later pages and CSV on the same fact boundary.

响应

listOwnRechargeOrders 响应
状态码说明
200Stable database snapshot

字段：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

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/recharges/orders

Create an authenticated tenant recharge order

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

全部需要：billing.account.read billing.recharges.create

参数

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

请求体

application/json · 必填：是

createRechargeOrder 请求体
名称类型必填说明
channelstring: alipay / wechat / transfer / usdt是—
amount_minorinteger(int64)是—

响应

createRechargeOrder 响应
状态码说明
201Created or exact replay

字段：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

失败时怎么办

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

↑ 回到列表

GET /v1/recharges/policy

Read the effective platform recharge policy for an authenticated tenant

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

全部需要：billing.account.read billing.recharges.create

说明（契约原文）

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.

参数

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

响应

getRechargePolicy 响应
状态码说明
200Current platform recharge policy

字段：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

失败时怎么办

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

↑ 回到列表