Skip to main content
POST
payment_instrument_id selects one of two signing modes:
  • Sign with an existing card: send payment_instrument_id. The instruction is CREATED, and the activation link opens the authorization page for that card.
  • Bind a card and sign: omit payment_instrument_id. The instruction is PENDING, and the activation link opens the card-binding and authorization flow, where the user binds a card and authorizes in one Passkey ceremony.
For the first mode, read payment_instrument_id from List payment methods. In the second mode, do not send a card number, CVV, or any other card field; the user enters card details on the Clink page. Customer identity always comes from the token; the request body has no customer or email field. After the activation link’s signing session is exchanged, an existing-card instruction continues to /authorize/{paymentInstrumentId}?instructionId=...; a bind-and-sign instruction continues to /bind-authorize?instructionId=..., where the user binds a card and authorizes in one Passkey ceremony.
Treat the activation link as a credential. Do not forward it, screenshot it, or write it to logs; anyone who has the link can open it while it is valid and obtain a Clink browser login session for that customer. Deliver it only to the intended user.

Activate the instruction

Creating an instruction is not an authorization. An instruction with an existing card is CREATED; an instruction that will bind a card is PENDING. Both become ACTIVE only after the user completes Passkey verification on Clink’s page. The link can be reopened or refreshed while it is valid, but the instruction can be signed only once.
  1. Send the user to activation_url in a browser.
  2. For CREATED, the user reviews the card and completes Passkey verification. For PENDING, the user binds a card and completes Passkey verification in the same ceremony. The page establishes the browser session and continues to the authorization step.
  3. Poll GET /agent/platform/authorizations/{instructionId} until status is ACTIVE.
If the user does not complete the flow, the instruction stays CREATED or PENDING and authorizes no spending. Only send the link to the intended user; it is an activation link, not a portal token.

Idempotency

request_id is the idempotency key, and the rules are identical in both signing modes. Clink keeps the idempotency record for 24 hours by default; after that window, retrying the same request_id creates a new instruction. Within the window, retrying with identical parameters returns the same instruction_id; a normal retry on an instruction that is not yet signed returns a fresh activation link. If the retried request_id refers to an instruction that is already signed or final, Clink returns the instruction without a new activation_url or activation_expires_at (both fields are omitted); read GET /agent/platform/authorizations/{instructionId} for the current status. Reusing a request_id with different parameters returns 409 with code 71211011 (portal_conflict).

Authorizations

Authorization
string
header
required

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

Body

application/json
request_id
string
required

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

Required string length: 8 - 128
Example:

"platform-ref-001"

title
string
required

Non-empty instruction title.

Minimum string length: 1
Example:

"Office supplies budget"

mandates
object[]
required

One or more mandates.

Minimum array length: 1
description
string

Instruction description.

Example:

"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.

Example:

"pi_..."

is_recurring
boolean

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

Example:

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.

Example:

"2026-12-31 23:59:59"

shipping_address
object

Shipping address.

Response

Success

code
integer<int32>

200 on success.

Example:

200

msg
string

Result message.

Example:

"Success"

data
object