能力与任务

能力告诉您某个客户是否可以使用特定的业务结果、支付方式和方向。待办任务告诉您在该能力或相关资源可以继续推进之前必须完成哪些事项。

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。

共享账户 vs 专属账户

银行类能力有两种变体,通过 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 '{}'

仅当您需要从受支持能力响应返回的 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

请从最新的任务中获取每个要求 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。仅当能力的当前状态允许您计划创建的账户、报价或转账时才继续。接下来,请在常见流程中选择匹配的路径。

开始使用

客户入驻

构建资金流

上线

发现受支持的能力

共享账户 vs 专属账户

申请能力

完成当前任务

托管操作

上传文件

API 答案

企业的受益所有人前提条件

在能力就绪时继续

​发现受支持的能力

​共享账户 vs 专属账户

​申请能力

​完成当前任务

​托管操作

​上传文件

​API 答案

​企业的受益所有人前提条件

​在能力就绪时继续

发现受支持的能力

共享账户 vs 专属账户

申请能力

完成当前任务

托管操作

上传文件

API 答案

企业的受益所有人前提条件

在能力就绪时继续