银行服务费用(
banking_customer、banking_account、banking_operation)为固定金额,在每笔操作执行时从您的 USDT 余额扣除,若操作失败则自动退款。费用为 0(默认值)时服务免费。每个响应中的 banking_fee 字段显示实际扣费金额。完整流程
- 创建您的银行客户档案(
POST /v1/banking/customer)——仅一次。 - 上传验证证件并提交审核。
- 状态变为
approved后,按货币开立账户。 - 登记收款人(交易对手)用于第三方付款。
- 发送付款:用
prepare询价,用operations执行。
banking_customer_status_changed 和 banking_operation_status_changed webhook 送达(webhooks)。
1. 创建您的银行客户档案
每个账户仅一次。若省略type、name 或 email,会从您的 CBPay 账户自动填充:
201:
409 banking_customer_exists。可随时查询状态:
2. 证件与验证
以 base64 格式上传每份证件(免费):draft → submitted → under_review → approved 或 rejected。每次变更都会由 banking_customer_status_changed webhook 通知:
3. 开立银行账户
档案变为approved 后,按货币各开立一个账户。可用货币:USD(ACH/Fedwire/SWIFT 通道)和 EUR(SEPA/SWIFT):
201——data 中包含用于接收资金的信息(账号/IBAN、路由号、银行):
个人账户限制:个人账户最多持有 1 个银行账户。尝试开立第二个会返回
409 banking_account_limit。企业账户没有限制。第三方用户(仅限企业)
如果您的账户是企业,除了您自己的账户外,还可以登记第三方银行用户——您的终端客户(个人或企业)——每个用户拥有自己的身份和验证,以及以其名义开立的银行账户。第三方数量及每个第三方的账户数量均无限制。登记第三方
登记需要该第三方一条已批准的 KYC/KYB 验证的verification_id——这是其在 CBPay 内的唯一身份。类型由验证种类决定(KYC ⇒ INDIVIDUAL,KYB ⇒ COMPANY),数据(姓名、邮箱、地址)会从已验证的档案自动填充(您显式提供的内容优先),并且已校验的证件会自动重新递交给银行服务提供方。此时计收银行客户档案费用(登记失败则退款):
201:
documents_synced 表示自动加载到该第三方银行档案中的验证证件数量。如果某份证件未能同步(或银行要求额外类别),请通过下方的手动证件流程上传,然后执行 submit。third_party_id:所有第三方路由都使用它。列出与查询(GET 中包含实时的验证状态):
第三方验证(免费)
与您自己的档案相同,只是作用于该第三方:第三方账户
第三方获批后,为其开立账户(同样计收banking_account 费用),操作方式与您自己的账户完全一致:
- 每个第三方只属于您:其他 CBPay 账户永远无法查看或操作它(会得到
404)。 - 个人账户尝试创建第三方会收到
403 company_required。 - 未提供
verification_id(或验证未获批准)时,登记会返回422 verification_required/422 verification_not_approved。如果发送的type与验证种类不匹配,则返回422 verification_kind_mismatch。在此规则之前创建的第三方继续正常运作。 - 已登记的第三方会计入您账户摘要中的”新用户”指标。
4. 登记收款人
要向第三方付款,需先用其银行信息登记收款人(免费;需经审核通过后方可使用):GET /v1/banking/counterparties 列出您的收款人,用 POST /v1/banking/counterparties/{id}/accounts 为已有收款人追加更多账户。
5. 发送付款
两种操作类型:
先询价(免费,不移动资金):
banking_operation 费用在此处计收):
202:
- 最终状态通过
banking_operation_status_changedwebhook 送达(completed/failed);您也可以轮询GET /v1/banking/operations/{id}。操作达到最终状态后,webhook 中会包含其receipt_url,并可通过GET /v1/banking/operations/{id}/receipt下载 PDF 凭证(凭证)。 - 使用相同
Idempotency-Key的重试会返回原始操作(idempotency_hit: true),不会再次收取费用。
带筛选条件的完整历史: