跳转到主要内容
POST
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。链接在有效期内可以重新打开或刷新,但指令只能签署一次。
  1. 让用户在浏览器中打开 activation_url。
  2. CREATED 指令由用户确认卡片并完成 Passkey 验证;PENDING 指令由用户在同一次 ceremony 中完成绑卡和 Passkey 验证。页面会建立浏览器登录态并继续到授权步骤。
  3. 轮询 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)。

授权

Authorization
string
header
必填

Portal user token from POST /agent/cwallet/platform/portal/tokens. Reads require portal:read; writes require portal:write.

请求体

application/json
request_id
string
必填

Platform-side reference and idempotency key, 8–128 characters.

Required string length: 8 - 128
示例:

"platform-ref-001"

title
string
必填

Non-empty instruction title.

Minimum string length: 1
示例:

"Office supplies budget"

mandates
object[]
必填

One or more mandates.

Minimum array length: 1
description
string

Instruction description.

示例:

"Monthly office supplies purchase"

payment_instrument_id
string

Existing usable payment instrument owned by the token's customer. Omit it to bind a new card and sign.

示例:

"pi_..."

is_recurring
boolean

Whether the instruction contains recurring mandates. When true, every mandate must include recurring_frequency.

示例:

false

effective_until_time
string

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"

shipping_address
object

Shipping address.

响应

Success

code
integer<int32>

200 on success.

示例:

200

msg
string

Result message.

示例:

"Success"

data
object