账户与钱包

每个账户都属于一个客户。请从两个维度进行选择:由谁管理,以及它是钱包还是银行账户。客户账户的列表、创建、读取、更新和归档操作位于 /v3/customers/{customerId}/accounts 下；单个账户操作再追加 /{accountId}。API 不支持从 accountId 反查 customerId。请将每个 accountId 与对应的 customerId 一起保存，以便后续请求能够访问该账户。

选择账户

账户	用途
发行的钱包	持有托管的稳定币余额、为出金提供资金、接收入金,或者作为发行银行账户的结算账户。
发行的银行账户	为客户提供可复用的银行账户信息,资金结算到一个发行的钱包。
外部钱包	记录该客户名下的一个区块链地址。
外部银行账户	记录该客户名下的一个银行账户,用于第一方出金。

issued 表示由 Swipelux 创建并管理该资源。external 用于记录客户名下的一个端点。第三方端点应放在收款方与目的地下,而不是客户账户列表中。在开始商户面板中用于银行卡或 Apple Pay 的 First pay-in 引导之前，请先为该客户创建 Polygon 钱包。该引导只提供这个 Polygon 钱包，没有它就无法继续。此先决条件仅适用于商户面板引导；直接 API 集成必须只使用为当前客户和能力返回的币种、网络、方法和账户类型。

创建账户

使用 POST /v3/customers/{customerId}/accounts。请在下述某一个请求体的基础上带上以下请求头:

X-API-Key: ${SWIPELUX_API_KEY}
Idempotency-Key: account-create-001
Content-Type: application/json

发行的钱包
发行的银行账户
外部钱包
外部银行账户

{
  "origin": "issued",
  "type": "wallet",
  "currency": "USDC",
  "network": "base",
  "label": "Settlement wallet"
}

{
  "origin": "issued",
  "type": "bank",
  "method": "ach",
  "country": "US",
  "currency": "USD",
  "settlement": {
    "accountId": "${SETTLEMENT_WALLET_ID}"
  },
  "label": "USD account"
}

{
  "origin": "external",
  "type": "wallet",
  "currency": "USDC",
  "network": "polygon",
  "details": {
    "address": "0x4997b0a68bebc1b0d80a93567ba7002be92b8b11"
  },
  "label": "Customer Polygon wallet"
}

{
  "origin": "external",
  "type": "bank",
  "methods": ["ach", "wire"],
  "country": "US",
  "currency": "USD",
  "details": {
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "accountType": "checking",
    "bankName": "Example Bank",
    "accountHolderName": "Acme Payments SAS"
  },
  "label": "Customer operating account"
}

请只使用为当前客户和能力所返回的币种、网络、支付方式和账户类型。切勿从其他客户或环境中照搬可用性信息。

等待账户变为可用

从创建响应中保存 data.id、data.status 和 data.openTaskIds。在报出转账报价或展示银行账户信息之前,请使用 GET /v3/customers/{customerId}/accounts/{accountId} 读取最新的账户。仅当账户当前的状态允许下一步操作时才使用该账户。如果存在未完成的任务 ID,请通过能力与任务完成它们。发行的银行账户在开通期间可能返回 details: null。仅在最新一次读取返回完整信息后才展示银行账户信息。如果 details.referenceRequired 为 true,请连同银行账户信息一起展示准确的 details.reference。

保持账户角色的明确性

对于出金,发行的钱包作为来源,填入 in.accountId。客户名下的银行账户作为 destinationId。对于发行的银行账户,settlement.accountId 是接收对账入金的发行钱包。接下来,请在接收资金、发送资金或发行银行账户中使用一个已就绪的账户。

开始使用

客户入驻

构建资金流

上线

选择账户

创建账户

等待账户变为可用

保持账户角色的明确性

​选择账户

​创建账户

​等待账户变为可用

​保持账户角色的明确性

选择账户

创建账户

等待账户变为可用

保持账户角色的明确性