信用卡 Onboarding

Markdown ChatGPT Claude

开始之前

您的 API 请求使用访问令牌进行身份验证。任何不包含有效访问令牌的请求都将返回错误。在身份验证中了解更多信息。

基础 URL

UAT：https://transactions.transactional.uat.unico.app/api/public/v1
生产环境：https://transactions.transactional.unico.app/api/public/v1

重要

信用卡 Onboarding既可以通过向终端用户请求自拍照并完成完整注册来执行，也可以通过复用其他 Unico IDCloud 平台产品所执行流程中的生物识别捕获来完成：

若要复用其他 IDCloud 产品生成的流程，请在 additionalInfo.processID 中提供参考流程 ID；
所使用的参考流程必须是在不超过 1 小时之前完成的。

验证信用卡

POST /walletid/transaction — 验证一张信用卡。

请求头

请求头	值
`Authorization`	`Bearer {token}` — 一个有效的访问令牌。

请求体

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "onboarding-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/wallet/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 5000.00,
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}

字段	类型	是否必填	描述
`identity`	object	是	用户身份信息。
`identity.key`	string	是	用户识别键的类型。
`identity.value`	string	是	用户识别键的值。
`orderNumber`	string	是	与该入驻流程关联的编号。用作门户中的索引，以及您的系统与无卡验证之间的外键。
`company`	string	是	负责该交易的公司 ID，由 Unico 提供。
`redirectUrl`	string	否	交易完成后用户被重定向到的 URL（Web 端为 HTTPS URL，原生移动应用为 Schema URL）。
`card`	object	是	交易中所用的卡片信息。
`card.binDigits`	string	是	卡片的前 8 位数字。
`card.lastDigits`	string	是	卡片的末 4 位数字。
`card.expirationDate`	string	否	卡片的到期日期。
`card.name`	string	是	持卡人姓名——请确保其正确，以避免编码问题或审批问题。
`value`	number	否	最高担保金额。
`additionalInfo`	object	否	发送此对象及 `processID`，以复用其他 Unico IDCloud 平台产品的生物识别捕获；和/或发送 `externalUserID`，为此交易启用静默验证。
`additionalInfo.processID`	string	否	来自 IDCloud 平台的参考流程 ID。
`additionalInfo.externalUserID`	string	否	与在采集设备元数据时通过 SDK 的 `externalUserId` 配置的标识符相同。仅在需要触发静默验证时才是必需的——如果缺失，交易仍会正常创建，但始终遵循标准可视化流程。

危险

orderNumber 字段必须填写该笔购买在电商系统中唯一的订单编号——使用不同的交易 ID 是不正确的做法，重复使用该值可能触发 replicated transaction 错误。

200 OK

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

字段	描述
`id`	已创建交易的 ID。
`status`	交易当前状态。
`link`	与该交易相关的链接。仅当未提供 `additionalInfo.processID` 时才会返回。
`token`	用于初始化无卡验证 Web SDK 的已签名令牌。仅当未提供 `additionalInfo.processID` 时才会返回。

备注

如果发送了 additionalInfo.externalUserID 且交易被静默批准，响应中也会省略捕获链接：

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

完整流程（包括 SDK 设置和时间要求）请参见静默验证。

查询验证状态

GET /walletid/transactions/{transaction_id} — 查询指定交易的当前状态。

请求头

请求头	值
`Authorization`	`Bearer {token}` — 一个有效的访问令牌。

200 OK

{
  "status": "processing",
  "hasIdentityChanged": false
}

字段	描述
`status`	交易的当前状态。
`hasIdentityChanged`	可选。该交易中是否发生了身份调换。

有关所有可能的状态，请参阅枚举。为优化性能，建议实现 Webhook，而非轮询此端点。

有关错误响应，请参阅错误 — 信用卡 Onboarding。

开始之前​

验证信用卡​

查询验证状态​

开始之前

验证信用卡

查询验证状态