> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Pay

> Create and track an Agent Payment Session.

Quick Pay is the direct payment-session path, suited to integrations that want to create a payment session and track its status with a small number of APIs.

## When to use Quick Pay

Use Quick Pay when your integration only needs a small number of APIs to create and query a direct payment session. Use UCP Pay when you need product and fulfillment state, and use Browser Pay when the Agent needs to operate a merchant web page.

## Payment flow

1. Create an Agent Payment Session with the payment amount, currency, and checkout context your integration requires.
2. When user action is required, give the returned `next_action` to the user or Agent unchanged.
3. Keep querying the session until it reaches a terminal state.
4. Treat the actual merchant or payment system result as authoritative before reporting success to the user.

### Sequence diagram

```mermaid theme={null}
sequenceDiagram
  participant U as User
  participant A as Agent
  participant M as Clink MCP
  participant O as Payment Operation
  participant P as Payment system
  participant S as Merchant

  U->>A: Provide a purchase or payment request
  A->>M: match_products (when needed)
  M->>S: Match merchant, product, and price
  S-->>M: Return available products and prices
  M-->>A: Return payment options
  A-->>U: Show merchant, product, and amount
  U->>A: Confirm the exact product, price, or top-up amount
  A->>M: quick_pay (confirmed: true)
  M->>O: Create payment Operation
  O-->>M: Success, next_action, or pending state

  alt Purchase authorization required
    M-->>A: SETUP_REQUIRED / PURCHASE_INSTRUCTION
    A-->>U: Show Passkey or authorization link
    U->>A: Complete authorization
    A->>M: get_operation
    M-->>A: Authorization complete
    A->>M: Resume quick_pay with the same payment facts
  else Card must be added or selected
    M-->>A: SETUP_REQUIRED / PAYMENT_METHOD
    A-->>U: Select an existing card or add a card
    U->>A: Complete the card action
    A->>M: Resume or reinitiate quick_pay with the same payment facts
  end

  M->>P: Execute one payment
  P->>S: Create order or complete top-up
  S-->>P: Return merchant result
  P-->>O: Return payment result
  O-->>M: Return terminal or pending state
  M-->>A: Return payment result

  alt Result unknown, pending, or connection interrupted
    A->>M: get_operation (same Operation)
    M-->>A: Return latest state
    A->>M: get_clink_order (known order ID)
    M-->>A: Return order status
  end

  A-->>U: Report the actual payment and order result
```

Use [Create Agent Payment Session](https://docs.clinkbill.com/api-reference/endpoint/create-agent-payment-session.md) to start and [Get Agent Payment Session](https://docs.clinkbill.com/api-reference/endpoint/get-agent-payment-session.md) to read the current state. Save the session identifier together with the original payment context; do not create a second session when the result is unknown.

## Code examples

### MCP

Let the Agent call the Quick Pay tools through MCP. The platform injects the user's authorization into the MCP connection and hands user confirmation, `next_action`, and Operation recovery to controlled Agent tools.

```markdown theme={null}
When handling a purchase, top-up, or "pay with Clink" request:

1. Call `match_products` first, and show the merchant, product, price, and currency.
2. Get the user's confirmation of the exact product or top-up amount.
3. Only after confirmation, call `quick_pay` once with `confirmed: true`.
4. Handle purchase authorization, payment methods, and user redirects according to the returned `next_action`.
5. When the result is unknown or the connection is interrupted, call `get_operation`; if you have an order ID, also call `get_clink_order`.
6. Report only the actual payment and order results returned by the server.
```

Do not give the MCP token or payment credentials to the model. When recovering, reuse the same Operation and the original payment facts; do not create a duplicate payment session.

### RESTful API

The server can call the Agent Payment Session API directly, save the session ID and original payment context, and query status using the same session:

```typescript theme={null}
async function createQuickPaySession(input: {
  customerEmail: string;
  amount: number;
  currency: string;
}) {
  const response = await fetch(`${API_BASE_URL}/order/payment-session`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${platformToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(input),
  });
  if (!response.ok) throw new Error(`Quick Pay API failed: ${response.status}`);

  const result = await response.json();
  await paymentSessionStore.save({
    sessionId: result.data.sessionId,
    ...input,
  });
  return result.data;
}

async function getQuickPaySession(sessionId: string) {
  const response = await fetch(
    `${API_BASE_URL}/order/payment-session/${encodeURIComponent(sessionId)}`,
    { headers: { Authorization: `Bearer ${platformToken}` } },
  );
  if (!response.ok) throw new Error(`Quick Pay API failed: ${response.status}`);
  return response.json();
}
```

If the Agent needs to use the RESTful API, wrap the create and query functions as controlled tools. The server validates user identity, amount, currency, and idempotency; the model must never obtain `platformToken`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.