Read APIs

All read APIs use the portal user token from Portal token. They are read-only and scoped to the token’s sub customer.

Authentication

Authorization: Bearer {PORTAL_TOKEN}

The gateway verifies aud=clink-agent-platform-portal, scope=portal:read, and token_use=access, then passes the verified customer identity to cwallet. There is no request parameter for selecting a different customer or email. Clink responses use the standard envelope:

{
  "code": 200,
  "msg": "Success",
  "data": {}
}

The examples below show data.

Common behavior

pageNum and pageSize use 1-based pagination.
Order lists accept status, from, and to filters.
Lists are scoped to the customer, not to an Agent. Orders, refunds, and authorizations created by any Agent for that customer are returned.
A missing record, or a record owned by another customer, is returned as 404.
There are no write endpoints in this API.

Get account

GET {API_BASE_URL}/agent/platform/me

{
  "customer_id": "ccus_...",
  "email": "user@example.com",
  "name": "Example User",
  "country": "US",
  "status": "READY"
}

Field	Meaning
`customer_id`	Clink customer ID.
`email`	Customer email.
`name`	Customer display name.
`country`	Billing address country, when available.
`status`	Wallet readiness: `READY`, `NOT_READY`, or `SUSPENDED`. `NOT_READY` means the account exists but has no usable default payment method.

List payment methods

GET {API_BASE_URL}/agent/platform/payment-methods

{
  "payment_methods": [
    {
      "payment_instrument_id": "pi_...",
      "payment_method_type": "CARD",
      "payment_instrument_type": "VIRTUAL_CARD",
      "card_scheme": "VISA",
      "card_last_four": "4242",
      "expiry_month": "12",
      "expiry_year": "2030",
      "issuer_bank": "Example Bank",
      "is_default": true,
      "status": "ACTIVE"
    }
  ]
}

status is ACTIVE or DISABLED. PAN and CVV are never returned.

List orders

GET {API_BASE_URL}/agent/platform/orders?pageNum=1&pageSize=20&status={STATUS}&from={ISO_DATE}&to={ISO_DATE}

Parameter	Required	Meaning
`pageNum`	No	Page number, starting at 1.
`pageSize`	No	Page size.
`status`	No	Order status filter.
`from`	No	Inclusive lower time bound.
`to`	No	Inclusive upper time bound.

{
  "total": 2,
  "page_num": 1,
  "page_size": 20,
  "truncated": false,
  "records": [
    {
      "order_id": "order_...",
      "paid_time": "2026-01-01T00:00:00Z",
      "amount": 42.5,
      "currency": "USD",
      "display_amount": "$42.50",
      "status_code": 1,
      "status": "SUCCESS",
      "merchant_name": "Example Merchant",
      "payment_method_type": "CARD",
      "payment_method_label": "Visa •••• 4242",
      "payment_method_icon": "https://...",
      "payment_instrument_last_four": "4242",
      "agent_info": {
        "clientId": "agent_..."
      }
    }
  ]
}

truncated: true means the status/time filtered scan reached Clink’s internal scan bound; total describes the records scanned, not necessarily the customer’s complete matching history. Without filters, the endpoint reads one page and does not use the bounded scan.

Get order

GET {API_BASE_URL}/agent/platform/orders/{orderId}

The detail response includes order time, amount breakdown, merchant, payment method, card scheme, products, shipping address and amount, agent_info, and a refund_summary:

{
  "order_id": "order_...",
  "order_time": "2026-01-01T00:00:00Z",
  "amount": 42.5,
  "display_amount": "$42.50",
  "subtotal_amount": 40.0,
  "display_subtotal_amount": "$40.00",
  "currency": "USD",
  "status_code": 1,
  "status": "SUCCESS",
  "merchant_name": "Example Merchant",
  "merchant_url": "https://merchant.example",
  "payment_method_type": "CARD",
  "payment_method_label": "Visa •••• 4242",
  "payment_instrument_last_four": "4242",
  "card_scheme": "VISA",
  "credit_amount": 2.5,
  "display_credit_amount": "$2.50",
  "paid_amount": 42.5,
  "display_paid_amount": "$42.50",
  "products": [],
  "agent_info": {},
  "refund_summary": {
    "refund_count": 0,
    "refunded_amount": 0,
    "currency": "USD",
    "latest_status": null,
    "refunds": []
  }
}

List refunds

GET {API_BASE_URL}/agent/platform/refunds?pageNum=1&pageSize=20

{
  "total": 1,
  "page_num": 1,
  "page_size": 20,
  "records": [
    {
      "refund_order_id": "refund_...",
      "order_id": "order_...",
      "refund_amount": 10.0,
      "refund_currency": "USD",
      "status": "SUCCESS",
      "refund_reason": "Customer request",
      "payment_instrument_id": "pi_..."
    }
  ]
}

Get refund

GET {API_BASE_URL}/agent/platform/refunds/{refundOrderId}

Returns one refund with the fields shown above. A refund owned by another customer is returned as 404.

List authorizations

GET {API_BASE_URL}/agent/platform/authorizations?pageNum=1&pageSize=20&status={STATUS}

Parameter	Required	Meaning
`pageNum`	No	Page number, starting at 1.
`pageSize`	No	Page size.
`status`	No	Authorization status filter.

{
  "total": 1,
  "page_num": 1,
  "page_size": 20,
  "records": [
    {
      "instruction_id": "inst_...",
      "client_reference_id": "platform-ref-1",
      "payment_instrument_id": "pi_...",
      "card_last_four": "4242",
      "card_type": "VIRTUAL_CARD",
      "card_scheme": "VISA",
      "title": "Example authorization",
      "description": "Purchase authorization",
      "total_amount_limit": 100.0,
      "currency_code": "USD",
      "effective_until_time": "2026-02-01T00:00:00Z",
      "is_recurring": false,
      "status": "ACTIVE",
      "agent_info": {},
      "mandates": [],
      "usages": []
    }
  ]
}

Get authorization

GET {API_BASE_URL}/agent/platform/authorizations/{instructionId}

The detail response includes the instruction fields, mandates, and usages. usages are raw usage records; compute used and remaining amounts from them when rendering the portal. An instruction owned by another customer is returned as 404.

Errors

HTTP status	Meaning
`400`	Invalid query parameters.
`401`	Missing, expired, or invalid portal token.
`403`	Wrong token audience, wrong scope, or a platform client token used instead of a portal token.
`404`	Record not found or not owned by the token’s customer.
`429`	Rate limit exceeded.

API Documentation

Clink MCP

Customize Agent Portal

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

Authentication

Common behavior

Get account

List payment methods

List orders

Get order

List refunds

Get refund

List authorizations

Get authorization

Errors

​Authentication

​Common behavior

​Get account

​List payment methods

​List orders

​Get order

​List refunds

​Get refund

​List authorizations

​Get authorization

​Errors

Authentication

Common behavior

Get account

List payment methods

List orders

Get order

List refunds

Get refund

List authorizations

Get authorization

Errors