ケイパビリティとタスク

ケイパビリティは、顧客が特定の成果、支払い方法、方向を利用できるかを示します。オープンタスクは、そのケイパビリティや関連リソースが進む前に何を完了する必要があるかを示します。

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 として保存します。他の顧客や環境からケイパビリティ ID をコピーしてはいけません。

プール型と名義型の口座タイプ

銀行ケイパビリティには 2 つのバリエーションがあり、accountType フィールドとケイパビリティ 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 '{}'

明示的な institutions 配列は、サポート対象ケイパビリティのレスポンスから返された ID を選択する必要がある場合にのみ使用してください。 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 に誘導してからタスクを再度取得してください。セッションレベルの 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 で 1 回送信します。

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

すべての要件 ID と回答タイプは、最新のタスクから取得してください。API がタスクの変更を報告した場合は、タスクを再取得し、新しいリビジョンから送信を再構築してください。

ビジネスにおける実質的支配者の前提条件

実質的支配者(beneficial owner)の証拠を必要とするビジネスケイパビリティのリクエストは、顧客に適格な所有者がまだ存在しない場合でも成功します。ケイパビリティは statusReason.code: tasks_due を伴う restricted として作成され、ビジネスインテークタスクが、所有構造を含む不足している所有の事実を要求します。同じタスクには、リクエストに qualification: "beneficial_owner" を含む resource_reference 要件が含まれます。

{
  "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 になった後であっても、要件が再度オープンされます。

ケイパビリティが ready になったら続行する

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 回答

ビジネスにおける実質的支配者の前提条件

ケイパビリティが ready になったら続行する

​サポートされているケイパビリティを発見する

​プール型と名義型の口座タイプ

​ケイパビリティをリクエストする

​現在のタスクを完了する

​ホスト型アクション

​ドキュメントをアップロードする

​API 回答

​ビジネスにおける実質的支配者の前提条件

​ケイパビリティが ready になったら続行する

サポートされているケイパビリティを発見する

プール型と名義型の口座タイプ

ケイパビリティをリクエストする

現在のタスクを完了する

ホスト型アクション

ドキュメントをアップロードする

API 回答

ビジネスにおける実質的支配者の前提条件

ケイパビリティが ready になったら続行する