发送资金

每次出金都从一个已就绪且有资金的发行钱包开始。目的地模型取决于该端点属于谁。

开始之前

请重新拉取来源钱包。确认其当前状态允许出金,并且可用余额足以支付预期的来源金额。将其响应中的 ID 保存为 SOURCE_WALLET_ID。您还需要一个针对当前客户与所选目的地的已就绪出金能力。现有的 Tron 钱包可以通过 stablecoin_transfers 报价将 USDT 发送到另一个 Tron 钱包。输入和输出必须使用相同的网络和稳定币。您无法在 Tron 上创建新的发行钱包。

1. 准备目的地

第一方
第三方

当端点属于客户本人时,请使用客户名下的外部银行账户。使用 POST /v3/customers/{customerId}/accounts 创建,并使用以下请求头:

Request headers

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

Request body

{
  "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"
}

使用 GET /v3/customers/{customerId}/accounts/{accountId} 读取该账户。仅当其当前状态允许出金时才继续。将其 acc_ 开头的 ID 保存为 PAYOUT_DESTINATION_ID。

通过收款方与目的地创建对应的个人或企业以及其银行或钱包端点。仅当目的地已就绪时才继续。将返回的 dst_ 开头的 ID 保存为 PAYOUT_DESTINATION_ID。切勿将收款方的 rcp_ 开头 ID 用作报价目的地。

2. 创建出金报价

使用 POST /v3/quotes 并使用以下请求头:

Request headers

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

Request body

{
  "customerId": "${CUSTOMER_ID}",
  "capabilityId": "${CAPABILITY_ID}",
  "in": {
    "amount": "150.00",
    "currency": "USDC",
    "accountId": "${SOURCE_WALLET_ID}"
  },
  "destinationId": "${PAYOUT_DESTINATION_ID}",
  "out": {
    "currency": "USD"
  }
}

将 data.id 保存为 QUOTE_ID,并展示返回的价格与费用。

选择银行路由

对于加密货币到法币的出金,您可以设置可选的 institutionId,要求使用为该客户批准的银行路由。省略该字段即可使用自动路由。

Request body with institutionId

{
  "customerId": "${CUSTOMER_ID}",
  "capabilityId": "${CAPABILITY_ID}",
  "institutionId": "${INSTITUTION_ID}",
  "in": {
    "amount": "150.00",
    "currency": "USDC",
    "accountId": "${SOURCE_WALLET_ID}"
  },
  "destinationId": "${PAYOUT_DESTINATION_ID}",
  "out": {
    "currency": "USD"
  }
}

显式指定的 institutionId 绝不会回退到其他银行。当所选银行没有针对该客户、能力和目的地的已就绪路由时,POST /v3/quotes 会返回 422 bank_not_supported_for_customer,指针为 /institutionId。
institutionId 仅适用于加密货币到法币的出金报价。在入金、银行卡或稳定币转账报价中发送该字段会返回 400 validation_error。
当可以识别银行时,报价和转账读取会回显所选路由的 institutionId,包括自动选择的路由。

SWIFT 出金

在生产环境中,USD SWIFT 出金需要一个支持出金的已就绪 SWIFT 能力(swift_pooled 或 swift_named),并由 Ethereum、Base 或 Polygon 上的 USDC,或 Ethereum 或 Polygon 上的 USDT 提供资金。扣除费用后的收款金额必须至少为 100.00 USD。 SWIFT 目的地需要在 bankAddress、bankCity、bankState 和 bankPostalCode 中提供银行的街道地址。BIC 国家必须与银行所在国家一致。Swipelux 会从客户或收款方资料中获取受益人地址。

Pix 出金

Pix 和 Pix Safe 收款方目的地接收 BRL。请使用客户已就绪的 Pix 能力（pix_pooled）为出金报价，以 USDC 提供资金，并将 out.currency 设置为 BRL。USDT 无法为 BRL 出金提供资金。 Pix 出金不能收取开发者费用。如果源账户设有开发者费用，请在报价请求中将 fees.breakdown.developer 设置为 {"fixed": "0.00", "bips": 0}。否则，POST /v3/quotes 会返回 400 validation_error。只有在目的地的银行信息获得批准后，Swipelux 才会为报价定价。在验证期间，POST /v3/quotes 会返回 400 validation_error，其 detail 说明目的地仍在验证中，因此请在验证完成后请求新的报价。如果银行信息被拒绝或目的地的设置不完整，detail 会要求您联系支持团队，在支持团队完成设置之前，新的报价会持续失败。如果无法检查验证状态，则会返回 503 quote_temporarily_unavailable；请稍后重试。

3. 执行出金

使用 POST /v3/transfers 创建转账。请为这次预期的执行使用一个新的幂等键:

Request headers

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

Request body

{
  "quoteId": "${QUOTE_ID}"
}

将转账的 data.id 保存为 TRANSFER_ID。创建成功意味着出金已启动,但并不代表已完成交付。

4. 跟踪交付

在创建之后以及每次事件之后,读取 GET /v3/transfers/{transferId}。请依据最新的 data.state、data.stateDetail 和 data.openTaskIds 来判断是继续等待、采取行动,还是展示一个终态结果。接下来,请查阅报价与转账以了解准确金额、安全的执行重试恢复,以及转账任务的处理。

开始使用

客户入驻

构建资金流

上线

开始之前

1. 准备目的地

2. 创建出金报价

选择银行路由

SWIFT 出金

Pix 出金

3. 执行出金

4. 跟踪交付

​开始之前

​1. 准备目的地

​2. 创建出金报价

​选择银行路由

​SWIFT 出金

​Pix 出金

​3. 执行出金

​4. 跟踪交付

开始之前

1. 准备目的地

2. 创建出金报价

选择银行路由

SWIFT 出金

Pix 出金

3. 执行出金

4. 跟踪交付