curl --request POST \
--url https://uat-api.clinkbill.com/agent/platform/authorizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"request_id": "platform-ref-001",
"title": "Office supplies budget",
"description": "Monthly office supplies purchase",
"payment_instrument_id": "pi_...",
"is_recurring": false,
"effective_until_time": "2026-12-31 23:59:59",
"shipping_address": {
"name": "Example User",
"line1": "1 Market Street",
"line2": "Suite 100",
"line3": null,
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country_code": "US"
},
"mandates": [
{
"description": "Purchase office supplies",
"amount_limit": "100.00",
"currency_code": "USD",
"recurring_frequency": null,
"merchant_category_code": "5732",
"preferred_merchant_name": null,
"effective_until_time": null
}
]
}
'{
"code": 200,
"msg": "Success",
"data": {
"instruction_id": "inst_...",
"status": "CREATED",
"payment_instrument_id": "pi_...",
"activation_url": "https://agent.clinkbill.dev/sign/ss_...",
"activation_expires_at": "2026-11-09T10:30:00Z"
}
}Authorizations
创建指令
Creates a purchase instruction (spending authorization) for the token’s customer and returns a short-lived activation link that the user opens to approve it with a Passkey. Requires portal:write.
POST
/
agent
/
platform
/
authorizations
curl --request POST \
--url https://uat-api.clinkbill.com/agent/platform/authorizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"request_id": "platform-ref-001",
"title": "Office supplies budget",
"description": "Monthly office supplies purchase",
"payment_instrument_id": "pi_...",
"is_recurring": false,
"effective_until_time": "2026-12-31 23:59:59",
"shipping_address": {
"name": "Example User",
"line1": "1 Market Street",
"line2": "Suite 100",
"line3": null,
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country_code": "US"
},
"mandates": [
{
"description": "Purchase office supplies",
"amount_limit": "100.00",
"currency_code": "USD",
"recurring_frequency": null,
"merchant_category_code": "5732",
"preferred_merchant_name": null,
"effective_until_time": null
}
]
}
'{
"code": 200,
"msg": "Success",
"data": {
"instruction_id": "inst_...",
"status": "CREATED",
"payment_instrument_id": "pi_...",
"activation_url": "https://agent.clinkbill.dev/sign/ss_...",
"activation_expires_at": "2026-11-09T10:30:00Z"
}
}payment_instrument_id 决定使用哪种签约模式:
- 指定卡签约:传
payment_instrument_id。指令状态为CREATED,激活链接打开该卡的授权页。 - 绑卡并签约:省略
payment_instrument_id。指令状态为PENDING,激活链接打开绑卡和授权流程,用户在一次 Passkey ceremony 中完成绑卡和授权。
payment_instrument_id。绑卡并签约时,不要发送卡号、CVV 或任何其他卡片字段;用户在 Clink 页面输入卡片信息。客户身份始终来自 token;请求体中没有 customer 或 email 字段。
激活链接的签名会话兑换完成后,指定卡指令继续进入 /authorize/{paymentInstrumentId}?instructionId=...;绑卡并签约指令继续进入 /bind-authorize?instructionId=...,用户在那里完成绑卡和授权(同一次 Passkey ceremony)。
把激活链接当作凭证处理。不要转发、截图或写入日志;拿到链接的人可以在链接有效期内打开它,并取得该客户的 Clink 浏览器登录态。只把链接发给目标用户。
激活指令
创建指令不等于授权。指定已有卡的指令状态为CREATED;需要绑卡的指令状态为 PENDING。两者都只有用户在 Clink 签名页完成 Passkey 验证后才变为 ACTIVE。链接在有效期内可以重新打开或刷新,但指令只能签署一次。
- 让用户在浏览器中打开
activation_url。 CREATED指令由用户确认卡片并完成 Passkey 验证;PENDING指令由用户在同一次 ceremony 中完成绑卡和 Passkey 验证。页面会建立浏览器登录态并继续到授权步骤。- 轮询
GET /agent/platform/authorizations/{instructionId},直到status为ACTIVE。
CREATED 或 PENDING,不会授权任何消费。链接只发给目标用户;它是激活链接,不是 portal token。
幂等
request_id 是幂等键,两种签约模式规则一致。Clink 默认保留幂等记录 24 小时;超过该窗口后,用同一 request_id 重试会新建一条指令。窗口内使用完全一致的参数重试会返回同一 instruction_id;对尚未签署的指令正常重试会返回新的激活链接。如果重试的 request_id 对应已签署或已终态的指令,Clink 返回该指令但不返回新的 activation_url 或 activation_expires_at(这两个字段会被省略);请读取 GET /agent/platform/authorizations/{instructionId} 获取当前状态。相同 request_id 携带不同参数返回 409,code 为 71211011(portal_conflict)。授权
请求体
application/json
Last time the instruction can be used, in UTC yyyy-MM-dd HH:mm:ss. Ignored in bind-and-sign mode: Clink overrides it (and each mandate's effective_until_time) with now + pendingActivationWindowMinutes (7 days by default), so read the effective value from the instruction.
示例:
"2026-12-31 23:59:59"