开始之前
您需要一个客户 ID、一个针对目标支付方式和币种的已就绪银行能力,以及一个属于同一客户的已就绪发行钱包。使用allowPending,您可以在所选银行仍在审核该客户期间保存该请求。请通过能力与任务完成所有待办事项。
1. 创建或选择结算钱包
通过账户与钱包创建一个发行的钱包,然后再次读取该钱包。仅当其当前状态允许结算时才继续。 将其响应中的data.id 保存为 SETTLEMENT_WALLET_ID。切勿将外部钱包用作 settlement.accountId。
2. 创建发行的银行账户
使用POST /v3/customers/{customerId}/accounts 并带上以下请求头:
Request headers
Request body
data.id 保存为 BANK_ACCOUNT_ID。同时保留 data.status、data.openTaskIds、data.details 以及结算关系。
可选请求字段:
选择银行
当客户需要来自特定银行的银行账户信息时,请发送institution。Swipelux 会为每个客户、支付方式、币种和机构的组合预留一个发行账户。如果客户已在任一银行拥有该支付方式和币种的发行账户,不带 institution 的请求会返回 409 conflict。带 institution 的请求仅在该银行的账户已存在时才会返回 409 conflict。
账户读取会以 institution 返回所选银行,其中包含 id、name 和 bic。bic 可能为 null。
幂等性作用于所选银行。重放相同的请求会返回原始账户。在同一个 Idempotency-Key 下更改 institution 会返回 409 idempotency_conflict。
在银行批准前保存请求
默认情况下,Swipelux 仅在银行能力就绪后才接受发行银行账户的请求。如需提前收集客户的账户设置,请同时发送allowPending: true 和 institution:
Request body with allowPending
status: "in_review",且 statusReason.code 为 waiting_for_approval。响应中还包含 applicationId 以及该申请的 openTaskIds。请通过能力与任务完成这些任务。
已保存的请求会保留其账户 ID、结算钱包和账户名额。待申请和能力就绪后,Swipelux 会在同一个 BANK_ACCOUNT_ID 下开通银行账户信息。请继续读取该 ID,切勿再创建新的请求。
已保存的请求在等待期间会占用该账户名额。针对同一名额、使用不同 Idempotency-Key 的另一个 allowPending 请求会返回 409 conflict。问题响应中的 holder.accountId 会指明正在等待的账户。请读取该账户,而不是重试。
如果申请先被拒绝、取消或归档,该账户会变为 rejected。它不再占用账户名额。
选择结算币种
默认情况下,入金以结算钱包的币种结算。将settlement.currency 设为 USDC 或 USDT,即可独立于钱包币种选择交付的资产:
Request body with settlement currency
USDT 需要一个 USD 账户,以及一个位于支持 USDT 交付的网络上的结算钱包。否则,该请求会返回 400 invalid_settlement_target。账户读取会返回已保存的选择,包括账户仍在开通期间。
银行账户 ID 与钱包 ID 承担不同的角色。使用银行账户 ID 来读取开通进度和银行账户信息。使用结算钱包 ID 来标识入金记账到哪里。
3. 监控开通进度
创建之后以及每次收到相关 Webhook 之后,请读取GET /v3/customers/{customerId}/accounts/{accountId}。
在 details 缺失期间,保持客户界面处于待处理状态。如果 openTaskIds 非空,请完成最新任务,然后重新拉取该账户。切勿仅凭经过的时间来推断就绪状态。
如果该账户是通过 allowPending: true 保存的,在银行批准申请之前,它会一直保持 in_review,且 statusReason.code 为 waiting_for_approval。
如果最新的 statusReason.code 为 awaiting_assignment,请通过接收资金为同一客户、能力和结算钱包创建第一笔入金,然后再次读取该银行账户。仅当当前账户明确要求时才走此分支。
4. 安全展示银行账户信息
请只展示最新一次账户读取所返回的完整信息。当details.referenceRequired 为 true 时,请展示准确的 details.reference 并允许复制。当其为 false 时,请勿自行编造 reference。
对于发行的 swift 账户,请在返回时展示 details.bankName、details.swiftCode(收款银行的 BIC)、details.accountNumber、details.accountHolderName 和 details.accountHolderAddress。汇款方必须将受益人地址原样填写到国际电汇中。同时请展示 details.bankAddress 以及账户返回的所有中间行字段。
这些银行账户信息是可复用的。切勿用来自某次获得报价入金中的入金指令替换它们,那些指令仅属于那一笔转账。
接下来,请添加 Webhook,让开通更新可以推送到您的应用,而无需让客户停留在轮询页面。