收款人與目的地

當該端點由客戶擁有時,請使用客戶帳戶。當資金由其他個人或企業接收時,請使用收款人與目的地。收款人記錄「誰」接收資金。目的地記錄他們「在哪裡」接收資金。

1. 建立收款人

使用 POST /v3/customers/{customerId}/recipients 建立個人或企業。請傳送以下標頭:

Request headers

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

Request body

{
  "type": "individual",
  "relationship": "contractor",
  "firstName": "Jason",
  "lastName": "Swipelux",
  "email": "jason@example.com",
  "phone": "+14155551234",
  "address": {
    "streetLine1": "1 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "label": "Jason contractor"
}

relationship 描述收款人與客戶之間的關係。請從 POST /v3/customers/{customerId}/recipients 請求 schema 中選擇一個值。若傳送 other，請勿新增搭配的自由文字欄位。Swipelux 會忽略請求 schema 未定義的欄位，因此該文字不會被儲存。在建立法幣目的地之前,請一併提供地址。將回傳的收款人 data.id 儲存為 RECIPIENT_ID,並保留其當前狀態。

2. 新增目的地

使用 POST /v3/customers/{customerId}/recipients/{recipientId}/destinations 建立端點。請為此目的地使用新的金鑰:

Request headers

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

銀行目的地
Pix 目的地
Pix Safe 目的地
錢包目的地

{
  "type": "ach",
  "currency": "USD",
  "details": {
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "accountType": "checking",
    "bankName": "Example Bank",
    "accountHolderName": "Jason Swipelux",
    "country": "US"
  }
}

{
  "type": "pix",
  "currency": "BRL",
  "details": {
    "pixKey": "jason@example.com",
    "accountHolderName": "Jason Swipelux"
  }
}

{
  "type": "pix_safe",
  "currency": "BRL",
  "details": {
    "taxId": "52998224725",
    "bankCode": "00000208",
    "branchCode": "0001",
    "accountNumber": "123456-7",
    "accountType": "checking",
    "accountHolderName": "Jason Swipelux"
  }
}

{
  "type": "wallet",
  "currency": "USDC",
  "ownership": {
    "type": "self_custodied"
  },
  "details": {
    "network": "base",
    "address": "0x1111111111111111111111111111111111111111"
  }
}

Pix 與 Pix Safe 目的地接收 BRL,且需要客戶已就緒的 Pix 能力(pix_pooled)。Pix 目的地會付款至 Pix 金鑰:僅含數字的 CPF 或 CNPJ、以 +55 開頭後接 10 或 11 位數字的電話號碼、電子郵件地址,或隨機金鑰。Pix Safe 目的地會付款至巴西銀行帳戶,該帳戶以 taxId 中持有人的 CPF 或 CNPJ、bankCode 中銀行的 8 位數 ISPB 代碼、分行,以及含檢查碼的帳號識別。回應與 webhook 會回傳遮罩後僅顯示末四碼的 taxId。建立銀行目的地時,Swipelux 會驗證 IBAN、BIC、ABA 銀行代碼以及 CPF 或 CNPJ 號碼等銀行識別碼,包括其檢查碼。格式錯誤的值會回傳 400 validation_error。這些檢查僅確認格式,並不確認帳戶是否存在或由誰持有。僅在收款人自身控管錢包時才使用 self_custodied。若錢包由其他托管方持有,請依照當前 API 參考中的相應變體處理。將回傳的目的地 data.id 儲存為 DESTINATION_ID,並保留其當前狀態。

3. 等待目的地就緒

於建立報價前,讀取 GET /v3/customers/{customerId}/recipients/{recipientId}/destinations/{destinationId}。僅在當前目的地狀態允許出金,且其幣別、方法與網路與預期的資金流動相符時繼續。收款人與目的地的狀態是互相獨立的。在出金報價中請使用 dst_ 開頭的目的地 ID。rcp_ 開頭的收款人 ID 標識擁有者紀錄,不是報價的目的地。接下來,請將就緒的目的地帶到發送資金。

開始使用

客戶引導

建立金流

上線

收款人與目的地

1. 建立收款人

2. 新增目的地

3. 等待目的地就緒

​1. 建立收款人

​2. 新增目的地

​3. 等待目的地就緒

1. 建立收款人

2. 新增目的地

3. 等待目的地就緒