Clink Payments Suite

Acknowledge processed event-hub events via POST /agent/event-hub/webhook-events/ack with body {eventIds}. Call AFTER Clink_PollEvents once events have been acted on, so the hub does not re-deliver them. AUTH: API key + timestamp ONLY — no X-Customer-ID (verified live 2026-07-06). eventIds is the array of eventId strings from the poll's data.records. Success = envelope code=200 with the acked ids. Never ack an event you have not actually processed.

Apply for a FULL refund of a completed order via POST /agent/cwallet/refund/apply with body {orderId}. Only on explicit Steward request in the current exchange, supplying the original order ID (must start order_). Partial refunds are NOT supported. WRITE operation requiring explicit Steward confirmation. Returns data.refundOrderId (starts rfd_) and status.

Cancel an external-merchant UCP checkout session via POST /agent/ucp/external/checkout-sessions/{checkout_id}/cancel (empty {} body). AUTH: X-Customer-API-Key + X-Timestamp + Idempotency-Key (no X-Customer-ID). Moves status to 'canceled'; use to abandon a session the Steward did not authorize or that resolved wrong (e.g. 0 totals). No money moves. UCP envelope (NOT the {code,msg,data} envelope): responses are {ucp:{version,status,...}, ...}. Success = HTTP 2xx and ucp.status != 'error' (create returns HTTP 201; get/cancel HTTP 200). Errors arrive HTTP 4xx with ucp.status 'error' and a messages[] array whose items carry code/content/severity (e.g. IDEMPOTENCY_KEY_REQUIRED, UCP_AUTHORIZATION_BINDING_INVALID 'instruction_id and mandate_id are required', UNSUPPORTED_SITE_TYPE 'only shopify sites supported', LINE_ITEM_ITEM_ID_REQUIRED). Report messages[].content verbatim on error.

Execute a DIRECT-MODE charge via POST /agent/order/charge with body containing paymentInstrumentId, paymentMethodType, merchantId, customAmount (JSON number UNQUOTED), and paymentCurrency. Used when no merchant payment session exists. customAmount must be EXACTLY the Steward-stated amount. WRITE operation requiring DOUBLE confirmation. Response and outcome handling identical to Clink_ChargeSession.

Execute a SESSION-MODE charge via POST /agent/order/charge. Session mode is the merchant-402-recovery path: the merchant created the payment session server-side and the session DEFINES the amount — never pass, invent, or restate an amount into this request. WRITE operation requiring explicit Steward authorization. Response: data.channelPaymentResponse and data.paySuccessInfo on success. Status 1=success, 3=declined, 4=risk-blocked, 6=other failure. flag3DS=1 means 3-D Secure required.

Execute a VIC-authorized SESSION charge via POST /agent/order/charge with body {paymentInstrumentId, paymentMethodType, sessionId, purchaseInstructionId} — same charge endpoint as Clink_ChargeSession plus the purchaseInstructionId referencing an ACTIVE, Passkey-signed purchase instruction. Use when a merchant returns HTTP 402 + session_id for a Visa purchase that requires agentic authorization: session defines the amount (never pass an amount), ACTIVE instruction supplies the Visa mandate. AUTH: full customer headers (X-Customer-ID + X-Timestamp + X-Customer-API-Key). PRECONDITION: instruction status MUST be ACTIVE (confirm via Clink_GetInstruction or purchase_instruction.activated event) — never charge against CREATED/PENDING draft. WRITE / REAL-MONEY operation: full step-8 charge-authorization gate, single-flight lock, amount reconciliation, 3DS handling, UNKNOWN-on-timeout rules apply EXACTLY as for Clink_ChargeSession.

COMPLETE an external-merchant UCP checkout — this is the REAL-MONEY charge — via POST /agent/ucp/external/checkout-sessions/{checkout_id}/complete. Body is the raw complete_body object EXACTLY {payment_instrument_id} (snake_case, emitted verbatim as the JSON body — no instruction_id/mandate_id/amount here; those were bound at create). AUTH: X-Customer-API-Key + X-Timestamp + Idempotency-Key (no X-Customer-ID). PRECONDITIONS (all mandatory): the session status is 'ready_for_complete'; the bound VIC instruction is ACTIVE (Passkey-signed — a CREATED/PENDING instruction cannot complete); the session totals reflect the REAL merchant price (re-fetch via Clink_GetCheckoutSession — never complete a 0-total or mismatched session); and the Steward has explicitly authorized THIS purchase in the current exchange (amount, merchant, item, card) per the step 8 charge gate. WRITE / real-money: the single-flight lock, 3DS handling, amount reconciliation, and UNKNOWN-on-timeout rules apply exactly as for the charge tools. On success the checkout status becomes 'completed' and the async result arrives as agent_order.succeeded on the event hub (poll via Clink_PollEvents); confirm merchant fulfillment via the merchant's own surface. UCP envelope (NOT the {code,msg,data} envelope): responses are {ucp:{version,status,...}, ...}. Success = HTTP 2xx and ucp.status != 'error' (create returns HTTP 201; get/cancel HTTP 200). Errors arrive HTTP 4xx with ucp.status 'error' and a messages[] array whose items carry code/content/severity (e.g. IDEMPOTENCY_KEY_REQUIRED, UCP_AUTHORIZATION_BINDING_INVALID 'instruction_id and mandate_id are required', UNSUPPORTED_SITE_TYPE 'only shopify sites supported', LINE_ITEM_ITEM_ID_REQUIRED). Report messages[].content verbatim on error.

Create an external-merchant agentic checkout session (UCP). SHOPIFY ONLY. item.price must be MINOR-UNIT INTEGER (HK.00 -> 41000). Omitting price resolves totals to 0. Verify totals match merchant real price before completing. Returns {id, status:ready_for_complete, continue_url, totals}. UCP envelope {ucp:{version,status},...} (create=201). IDEMPOTENCY_KEY_REQUIRED error if key missing. Report messages[].content on error.

Create a VIC (Visa Intelligent Commerce) purchase-instruction DRAFT via POST /agent/cwallet/instructions. A purchase instruction is the Visa agentic-authorization mandate that must exist and be Passkey-signed before an agent can charge a Visa purchase. AUTH: API key + timestamp ONLY — no X-Customer-ID (verified live 2026-07-06). Body = instruction_body object: paymentInstrumentId, a human-readable title, and a REQUIRED mandates array where EACH mandate carries its own amountLimit + currencyCode. effectiveUntilTime is UTC 'yyyy-MM-dd HH:mm:ss' (epoch seconds REJECTED). NEVER send clientReferenceId/channelTokenId/consumerId — the server derives them. Success returns data.instructionId with data.status='CREATED' plus mandates. The response does NOT contain a passkeyUrl — the Mind BUILDS it: https://agent.clinkbill.com/passkey-auth/{paymentInstrumentId}?type=visa&instructionId={instructionId}. A CREATED draft moves NO money; must be Passkey-signed to reach ACTIVE. See VIC step in the skill.

Generate a hosted card-binding link AND list currently bound payment methods via POST /agent/cwallet/card/bindingLink (send a literal {} JSON body — empty object, not a bodiless POST). Returns data.bindingUrl (Clink-hosted secure page; production form verified 2026-07-03: https://agent.clinkbill.com/login?email=<base64-email>; opening it auto-sends a 6-digit verification code to the wallet email, so the wallet address must be a mailbox the Steward receives — send to the Steward VERBATIM; never parse, decode, store, or reuse any token embedded in the URL; treat every returned URL as single-use and re-mint rather than reuse — whether Clink rotates the URL per call is unverified) and data.paymentMethodsVoList (bound instruments — empty array means no payment method bound yet; item fields verified live on production 2026-07-03: paymentInstrumentId 'cpi_...', cardScheme, cardLastFour, expiryMonth, expiryYear, issuerBank, isDefault, isDisabled, visaRegistrationSucceeded, paymentInstrumentType 'CARD', wallet). Triple duty: (1) card binding — Steward enters card data on Clink's hosted page, card data never transits the Mind; (2) list payment methods — the response list is the only trustworthy source; (3) binding-completion poll — after sending the link, re-call every ~60 seconds (max ~10 minutes in-turn) until the new instrument appears in paymentMethodsVoList. Success ONLY when envelope code=200. Errors: HTTP 401 envelope code 401 'Timestamp parameter is missing' (regenerate X-Timestamp, retry once — pre-execution rejection), HTTP 401 envelope code 401 'invalid.customer.api.key' (the customer_api_key sent is wrong or missing — re-read this Mind's TENET 'clink' entry and retry once; if it persists, the entry needs re-provisioning via the step 4 setup/recovery ceremony: a bootstrap re-run with the exact original parameters, or a one-time Steward re-delivery inside that ceremony — never ask for the key in chat outside that ceremony, never echo it, never store it in LTM), CUSTOMER_VERIFY_FAILED (email/key mismatch — security block, NO retry; documented on payment flows and may also surface here).

Fetch an external-merchant UCP checkout session via GET /agent/ucp/external/checkout-sessions/{checkout_id}. AUTH: X-Customer-API-Key + X-Timestamp ONLY (no X-Customer-ID, no Idempotency-Key on GET). Returns the current session {id, status ('ready_for_complete' | 'canceled' | 'completed' | ...), currency, line_items, totals, buyer, continue_url, expires_at}. Use it to re-read totals (verify price populated) and confirm status before completing. UCP envelope (NOT the {code,msg,data} envelope): a successful GET returns HTTP 200 with {ucp:{version,status},id,status,currency,line_items,totals,buyer,continue_url,expires_at}. Errors arrive HTTP 4xx with ucp.status 'error' and a messages[] array (code/content/severity, e.g. a not-found id) — report messages[].content verbatim. GET is read-only: it takes no Idempotency-Key and cannot return write-only errors like IDEMPOTENCY_KEY_REQUIRED.

Fetch one VIC purchase instruction by ID via GET /agent/cwallet/instructions/{purchase_instruction_id}. Primary use: confirm a draft has been Passkey-signed and reached status ACTIVE before charging against it. AUTH: API key + timestamp ONLY — no X-Customer-ID (verified live 2026-07-06). Success returns data with instructionId, status (CREATED before signing, ACTIVE once authorized), title, mandates, activatedAt, effectiveUntilTime, cardScheme/cardLastFour. Never treat CREATED or PENDING as authorized.

Poll refund progress via GET /agent/cwallet/refund/{refundOrderId}. Returns data.status with lifecycle: pending_review, refunding, then terminal success, failed, or review_rejected. Report status verbatim; never report refunded before terminal success; on review_rejected, report it and do NOT auto-reapply.

List VIC purchase instructions for a payment instrument via GET /agent/cwallet/instructions?status={status}&paymentInstrumentId={payment_instrument_id}. REUSE-FIRST: an existing ACTIVE instruction covering the intended merchant scope + amount should be semantically reused, not duplicated. AUTH: API key + timestamp ONLY — no X-Customer-ID (verified live 2026-07-06). status enum: CREATED, ACTIVE, PENDING, CANCELLED, EXPIRED, DECLINED. Success returns data as an array of instruction objects; an empty array means none in that status. Only status ACTIVE authorizes a charge.

Drain the Clink event hub via POST /agent/event-hub/webhook-events/poll with body {pageSize}. How the Mind observes ASYNC completion instead of guessing: payment_method.added (card binding), agent_order.succeeded/failed (charge result), agent_refund.* (refund lifecycle), purchase_instruction.activated (VIC signed), vic_device.binding_succeeded (Visa registration). AUTH: API key + timestamp ONLY — no X-Customer-ID (verified live 2026-07-06). Success returns data.records[] with eventId, eventType, resourceId, businessStatus, eventTime, payload. Filter by eventType CLIENT-SIDE. Empty records means nothing new yet. After processing, ACK with Clink_AckEvents.

Update an external-merchant UCP checkout session via PUT /agent/ucp/external/checkout-sessions/{checkout_id} (change line_items, buyer, shipping_address, or metadata before completion). AUTH: X-Customer-API-Key + X-Timestamp + Idempotency-Key (no X-Customer-ID). update_body is emitted as the raw JSON body. Only valid before the session is completed/canceled. ANY update INVALIDATES a prior totals check and any Steward charge authorization for this session (the STREAM clink_pending_auth grant is void): after updating you MUST re-fetch with Clink_GetCheckoutSession, re-verify the totals are non-zero and match, and re-run the step 8 Steward charge gate before Clink_CompleteCheckout — never complete against a total the Steward authorized before the update. UCP envelope (NOT the {code,msg,data} envelope): responses are {ucp:{version,status,...}, ...}. Success = HTTP 2xx and ucp.status != error. Errors arrive HTTP 4xx with ucp.status error and a messages[] array whose items carry code/content/severity (e.g. IDEMPOTENCY_KEY_REQUIRED, UCP_AUTHORIZATION_BINDING_INVALID, UNSUPPORTED_SITE_TYPE, LINE_ITEM_ITEM_ID_REQUIRED). Report messages[].content verbatim on error.