發送資金

每一筆出金都從已就緒且已入金的發行錢包開始。目的地模型取決於該端點的擁有者。

開始前

重新讀取來源錢包。確認其當前狀態允許出金,且可用餘額涵蓋預期的來源金額。將回應取得的 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. 追蹤送達