跳转到主要内容

支付交易

MarkdownChatGPTClaude

开始之前​

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

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

创建交易​

POST /credit/transaction — 创建一笔新交易。

危险

为确保更好的转化率，请仅在完成任何可能在无卡验证体验之前就终结该操作的预身份验证或校验之后，才创建交易。

危险

orderNumber 字段必须填写该笔购买在电商系统中唯一的订单编号——使用不同的交易 ID 是不正确的做法。重复使用它可能导致转化率降低（订单编号有助于终端用户完成流程），并可能导致 API 错误，例如在使用相同订单编号、CPF、BIN 和末 4 位数字时出现的 replicated transaction 错误。

请求头
请求头值
AuthorizationBearer {token} — 一个有效的访问令牌。
请求体
{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "order-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/checkout/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 199.90,
  "mainContacts": [
    { "key": "phone", "value": "5543999999999" }
  ],
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}
字段类型是否必填描述
identityobject是用户识别数据。
identity.keystring是用户识别键的类型。建议使用 cpf——转化率更高。
identity.valuestring是用户识别键的值，不含点号或连字符。
orderNumberstring是与该交易关联的订单编号。用作门户中的索引，以及您的系统与无卡验证之间的外键。
companystring是负责该交易的公司 ID，由 Unico 提供。
redirectUrlstring否交易完成后用户被重定向到的 URL（Web 端为 HTTPS URL，原生移动应用为 URL scheme）。
cardobject是交易中所用卡片的信息。
card.binDigitsstring是卡片的前 8 位数字。
card.lastDigitsstring是卡片的末 4 位数字。
card.expirationDatestring否卡片的到期日期。
card.namestring是持卡人姓名。请正确发送，避免编码问题——该数据会被用于用户体验和沟通中。
valuenumber是购买总金额。
mainContactsarray否用于通知用户的主要联系方式（邮箱和/或电话）列表，适用于由无卡验证负责通知的情形。
fallbackContactsarray否备用联系方式列表，当主要联系方式的通知尝试失败时触发。
additionalInfoobject否发送该对象并附带 externalUserID，以为该笔交易启用静默验证。
additionalInfo.externalUserIDstring是（如果发送了 additionalInfo）与通过 SDK 的 externalUserId 在采集设备元数据时配置的标识符相同。触发静默验证所必需——如果未提供，交易仍会正常创建，但始终遵循标准可视化流程。
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...",
  "expiresAt": "2026-07-22T15:30:00Z"
}
字段描述
id已创建交易的 ID。
status交易当前状态。
link与该交易相关的链接。
token已签名的令牌，包含初始化无卡验证 Web SDK 所需的参数。
expiresAt交易的过期日期和时间，ISO 8601 格式（UTC）。
警告

如果验证结果表明无需进行生物识别捕获，响应将呈现不同的状态，且不会生成捕获链接：

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

当结账（Checkout）使用 Pre 或 Super Pre 模块时会出现这种情况，详见功能。

备注

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

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

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

有关错误响应，请参阅错误 — 交易创建。

获取交易状态​

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

请求头
请求头值
AuthorizationBearer {token} — 一个有效的访问令牌。
200 OK
{
  "status": "processing"
}
字段描述
status交易的当前状态。

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

有关错误响应，请参阅错误 — 获取交易状态。

获取交易证据集​

GET /credit/transactions/{transaction_id}/probative — 获取指定交易的证据集。

警告

证据集只能针对已批准的交易生成。

危险

证据集返回的链接自获取之日起五分钟内有效——请勿保存该链接，应立即使用它下载证据集。

请求头
请求头值
AuthorizationBearer {token} — 一个有效的访问令牌。
200 OK
{
  "link": "https://unico.io/probative.pdf"
}
字段描述
link证据文件的 URL。

有关错误响应，请参阅错误 — 获取交易证据集。

重新发送交易通知​

POST /credit/transactions/{transaction_id}/notify — 通过邮件和/或电话重新发送指定交易的通知。

备注

也可以通过门户配置通知重发，而无需通过 API 实现。请与您项目的对接人沟通以了解具体可行方案。

请求头
请求头值
AuthorizationBearer {token} — 一个有效的访问令牌。
请求体
{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}
字段类型是否必填描述
phonestring是用于发送通知的电话号码。
emailstring是用于发送通知的邮箱地址。
200 OK
{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}
字段描述
id生成的通知的唯一 ID。
link为该通知生成的链接。

有关错误响应，请参阅错误 — 重新发送交易通知。

最后更新 于