客户 - 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}"

查找有待提交文件的客户

要找出某一页中哪些客户仍需提交必需文件,请向 GET /v3/customers 传入 include=documentRequirements。你可以将其与能力摘要组合使用,写作 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。接下来,请前往能力与任务,以发现并启用您所需的产品结果。

开始使用

客户入驻

构建资金流

上线

客户

个人客户

企业客户

通过能力读取就绪状态

查找有待提交文件的客户

​个人客户

​企业客户

​添加企业相关人员

​通过能力读取就绪状态

​查找有待提交文件的客户

个人客户

企业客户

添加企业相关人员

通过能力读取就绪状态

查找有待提交文件的客户