能力與任務

能力(capability)會告訴您客戶是否能使用特定的結果、支付方式與方向。待辦任務(open tasks)則告訴您在該能力或相關資源可以繼續之前必須完成哪些事項。

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

探索支援的能力

使用 GET /v3/customers/{customerId}/capabilities/supported 讀取客戶當前可用的選項:

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

選擇符合預期 directions、method 與 accountType 的回應項目。僅在 availability 為 available 或 beta,且 eligibility.eligible 為 true 時繼續。若回傳了 institutions,僅從該回應中選擇一個 ID。將選定的 data[].id 儲存為 CAPABILITY_ID。切勿從其他客戶或其他環境複製 capability ID。

共用型與專屬型帳戶類型

銀行能力有兩種變體,分別以 accountType 欄位與 capability ID 尾綴(例如 ach_pooled、wire_named)標示:

pooled: 共用的 Swipelux 銀行帳戶。每筆入金使用唯一的參考編號來路由資金。用於一次性轉帳。
named: 為客戶專屬的銀行資料(虛擬 IBAN、專屬 ACH 帳戶)。可重複使用並可與任何付款人分享。發行銀行帳戶必須使用此類型。

預設請採用 pooled。僅在客戶需要可重複使用的銀行資料時才使用 named。可在 supported 回應中查看有哪些變體可用。

申請能力

使用 POST /v3/customers/{customerId}/capabilities/{capabilityId} 申請所選的選項:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: capability-request-001" \
  --header "Content-Type: application/json" \
  --data '{}'

僅在您需要從支援能力回應所提供的 ID 中挑選時,才使用明確的 institutions 陣列。將 data.status 儲存為 CAPABILITY_STATUS、data.openTaskIds 儲存為 OPEN_TASK_IDS,並將每個 data.applications[].id 存入 APPLICATION_IDS。

完成當前任務

使用 GET /v3/customers/{customerId}/tasks 列出任務,從 OPEN_TASK_IDS 中選擇 ID,然後使用 GET /v3/customers/{customerId}/tasks/{taskId} 讀取每個當前任務:

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

請使用最新的 data.revision 與 data.requirements。若兩者中任一可能已變更,請在提交前立即重新讀取任務。每個未完成任務都包含 dueAt 時間戳記。當 Swipelux 建立任務且未明確指定到期日期時,dueAt 預設為任務 createdAt 之後整整 31 天。請將 dueAt 視為僅供參考:您無法透過 API 設定它,它也不會觸發任何自動生命週期轉換。只有單獨的 deadline 欄位(如存在)才會觸發自動轉換。

託管操作

在任務詳細資料回應中，verificationSessions 與 tosSessions 的每一筆項目都包含 action 物件。任務清單回應不包含這些動作連結。請儲存每個工作階段的 id，並在引導客戶前讀取 action.kind；不要從工作階段的 status 推斷連結是否可用。

action.kind: "available" 會包含 action.url 與 action.expiresAt（目前一律為 null）。請儲存 action.url，將客戶引導至該網址，然後再次讀取任務。工作階段層級的 url 與 expiresAt 欄位包含相同的值。
action.kind: "unavailable" 表示不應顯示連結。工作階段層級的 url 與 expiresAt 欄位不存在。僅憑工作階段的 status 無法判定會收到哪種動作類型。

{
  "data": {
    "verificationSessions": [
      {
        "id": "vfy_000000000000000003",
        "key": "identity_verification",
        "type": "identity_verification",
        "status": "action_required",
        "action": {
          "kind": "available",
          "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
          "expiresAt": null
        },
        "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
        "expiresAt": null
      }
    ],
    "tosSessions": [
      {
        "id": "vfy_000000000000000004",
        "key": "terms_of_service",
        "type": "terms_of_service",
        "status": "completed",
        "action": { "kind": "unavailable" }
      }
    ]
  }
}

這些是與任務相關的操作,而不是獨立的客戶驗證生命週期。

上傳文件

當要求提供文件時,請使用 POST /v3/customers/{customerId}/documents 上傳:

export DOCUMENT_PATH='/absolute/path/to/requested-document.pdf'

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/documents" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-document-001" \
  --form "file=@${DOCUMENT_PATH}"

在提交引用該文件的答覆前,將回傳的 data.id 儲存為 DOCUMENT_ID。

API 答覆

使用 POST /v3/customers/{customerId}/tasks/{taskId}/submissions 為當前版本提交一組完整的答覆:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: task-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "taskRevision": 3,
  "answers": [
    {
      "requirementId": "req_from_current_task",
      "answer": {
        "type": "text",
        "value": "Current answer"
      }
    }
  ]
}
JSON

請從最新的任務中取用每個 requirement ID 與答覆類型。若 API 回報任務已變更,請重新讀取,並根據新版本重新建構提交內容。

企業的最終受益人前置條件

申請需要最終受益人佐證的企業能力,即使客戶尚未有符合資格的所有者,也會成功。該能力會以 restricted 建立,並帶有 statusReason.code: tasks_due,而企業資料收集任務會要求缺少的所有權事實,包括所有權結構。同一任務帶有一項 resource_reference 要求,其請求包含 qualification: "beneficial_owner":

{
  "type": "resource_reference",
  "prompt": "Add or select a qualifying beneficial owner.",
  "required": true,
  "resourceType": "related_party",
  "qualification": "beneficial_owner"
}

當關係人為同一客戶名下的有效 person 關係人,且具有 ownership.declared: true 或提供的所有權比例達 25 以上時,即符合資格。該要求是從當前的關係人名冊推導而來,因此您通常不會直接答覆它:

建立或更新符合資格的關係人,會在同一次重新評估中滿足該要求,並開啟該所有者本身的個人資料與文件工作。請參閱新增企業關係人。
您也可以使用帶有其 relatedPartyId 的 resource_reference 答覆,明確引用符合資格的關係人。
該要求在被滿足後仍會列在當前任務中。當沒有其他未完成的義務時,任務會變為 satisfied。
封存最後一位符合資格的關係人,或移除使其符合資格的事實,會重新開啟該要求,即使任務先前已為 satisfied。

能力就緒後繼續

使用 GET /v3/customers/{customerId}/capabilities/{capabilityId} 再次讀取能力:

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

將儲存的狀態與任務 ID 替換為最新的回應。僅在當前能力狀態允許您預期建立的帳戶、報價或轉帳時才繼續。接下來,請於常見流程中選擇對應的路徑。

開始使用

客戶引導

建立金流

上線

探索支援的能力

共用型與專屬型帳戶類型

申請能力

完成當前任務

託管操作

上傳文件

API 答覆

企業的最終受益人前置條件

能力就緒後繼續

​探索支援的能力

​共用型與專屬型帳戶類型

​申請能力

​完成當前任務

​託管操作

​上傳文件

​API 答覆

​企業的最終受益人前置條件

​能力就緒後繼續

探索支援的能力

共用型與專屬型帳戶類型

申請能力

完成當前任務

託管操作

上傳文件

API 答覆

企業的最終受益人前置條件

能力就緒後繼續