客戶 - Swipelux

在建構入金、出金或發行銀行帳戶之前,請先建立客戶。能力、帳戶與轉帳的範圍都限定於該客戶。請以 externalId 作為與您系統中對應紀錄的穩定映射。

Environment variables

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

個人客戶

個人客戶僅需 type。請一併提供您已知的個人資料欄位,並僅在當前能力或任務需要時再新增其他欄位。使用 POST /v3/customers 建立客戶:

Create individual customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-user-123" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "individual",
  "externalId": "user_123",
  "individual": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

將回傳的 data.id 儲存為 CUSTOMER_ID。政策背景請參閱個人入駐。

企業客戶

企業客戶需要提供 business.legalName。使用相同的操作建立企業:

Create business customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-company-456" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "business",
  "externalId": "company_456",
  "business": {
    "legalName": "Acme Payments SAS"
  }
}
JSON

將回傳的 data.id 儲存為 CUSTOMER_ID。政策與文件相關內容請參閱企業入駐。當董事、股東等其他企業參與者已知或被要求時,請將其新增。此範例使用 POST /v3/customers/{customerId}/related-parties 建立一位董事:

Add related party

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/related-parties" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: related-party-director-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "partyType": "person",
  "roles": ["director"],
  "title": "Chief executive officer",
  "person": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

將回傳的 data.id 儲存為 RELATED_PARTY_ID。如需匯出客戶資料，請使用 POST /v3/customers/{customerId}/export 並遵循其請求 schema。json_basic_data 格式會以 JSON 附件回傳當前的公開 v3 客戶資源;每次呼叫都會重新計算當前資料,且不包含文件與文件中繼資料。若需可攜性權杖格式,請在 forClientId 中傳送接收方 KYC 專案的 client ID,而非 Swipelux 的 customerId。請在 data.expiresAt 之前使用回傳的 data.token。重複使用相同的 Idempotency-Key 與請求主體會重播該權杖結果;若要核發另一組權杖,請使用新的金鑰。

從能力讀取就緒狀態

客戶在 API 中並不具備驗證或就緒狀態。請使用 GET /v3/customers/{customerId} 讀取當前的個人資料,然後利用能力及其 openTaskIds 來判斷該客戶接下來可以做什麼。

Get customer

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

找出有待提交文件的客戶

若要找出某一頁中哪些客戶仍需提交必要文件,請將 include=documentRequirements 傳給 GET /v3/customers。你可以將其與能力摘要組合使用,寫作 include=capabilities,documentRequirements。API 金鑰需要 accounts:read 權限才能使用 documentRequirements 擴充。此時,每個客戶摘要都會包含一個 documentRequirements 物件:

Document requirement summary

{
  "documentRequirements": {
    "required": true,
    "count": 2
  }
}

count 是處於 action_required 狀態、且所屬任務也處於 action_required 狀態的必要文件要求數量。它涵蓋所有任務範圍,包括帳戶層級的任務,且不取決於能力的就緒狀態。
當 count 大於 0 時,required 為 true。
一組替代方案只計算一次,且僅在每個替代方案都需要文件時才計入。

此摘要採取保守做法。它不包含選用文件、有條件必要的文件,以及混合文件與非文件途徑的替代方案。它也不包含客戶可透過託管驗證完成的要求。因此,required: false 並不能證明沒有適用的文件任務。請用它來排定客戶的優先順序,然後讀取其任務,以取得需要收集內容的權威清單。若未使用此擴充,回應會省略 documentRequirements。接下來,請繼續前往能力與任務,以探索並啟用您需要的產品結果。

開始使用

客戶引導

建立金流

上線

客戶

個人客戶

企業客戶

從能力讀取就緒狀態

找出有待提交文件的客戶

​個人客戶

​企業客戶

​新增企業關係人

​從能力讀取就緒狀態

​找出有待提交文件的客戶

個人客戶

企業客戶

新增企業關係人

從能力讀取就緒狀態

找出有待提交文件的客戶