> ## 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

> 创建并跟踪 Agent Payment Session。

Quick Pay 是直接支付会话方案，适合希望通过较少 API 创建支付会话并跟踪状态的集成。

## 什么时候使用 Quick Pay

当集成只需要通过少量 API 创建和查询直接支付会话时，使用 Quick Pay。需要商品和履约状态时使用 UCP Pay；需要 Agent 操作商户网页时使用 Browser Pay。

## 支付流程

1. 使用集成所需的支付金额、币种和结账上下文创建 Agent Payment Session。
2. 需要用户操作时，将返回的 `next_action` 原样交给用户或 Agent。
3. 持续查询会话，直到进入终态。
4. 以商户或支付系统的实际结果为准，再向用户报告成功。

### 时序图

```mermaid theme={null}
sequenceDiagram
  participant U as 用户
  participant A as Agent
  participant M as Clink MCP
  participant O as Payment Operation
  participant P as 支付系统
  participant S as 商户

  U->>A: 提供购买或支付请求
  A->>M: match_products（需要时）
  M->>S: 匹配商户、商品与价格
  S-->>M: 返回可用商品和价格
  M-->>A: 返回支付选项
  A-->>U: 展示商户、商品、金额
  U->>A: 确认准确商品、价格或充值金额
  A->>M: quick_pay（confirmed: true）
  M->>O: 创建支付 Operation
  O-->>M: 成功、next_action 或等待状态

  alt 需要购买授权
    M-->>A: SETUP_REQUIRED / PURCHASE_INSTRUCTION
    A-->>U: 展示 Passkey 或授权链接
    U->>A: 完成授权
    A->>M: get_operation
    M-->>A: 授权完成
    A->>M: 使用同一支付事实恢复 quick_pay
  else 需要添加或选择卡片
    M-->>A: SETUP_REQUIRED / PAYMENT_METHOD
    A-->>U: 选择已有卡或添加卡片
    U->>A: 完成卡片操作
    A->>M: 使用同一支付事实恢复或重新发起 quick_pay
  end

  M->>P: 执行一次支付
  P->>S: 创建订单或完成充值
  S-->>P: 返回商户结果
  P-->>O: 返回支付结果
  O-->>M: 返回终态或等待状态
  M-->>A: 返回支付结果

  alt 结果未知、等待或连接中断
    A->>M: get_operation（同一 Operation）
    M-->>A: 返回最新状态
    A->>M: get_clink_order（已知订单 ID）
    M-->>A: 返回订单状态
  end

  A-->>U: 报告实际支付和订单结果
```

使用[创建 Agent Payment Session](https://docs.clinkbill.com/api-reference/endpoint/create-agent-payment-session.md)开始，使用[查询 Agent Payment Session](https://docs.clinkbill.com/api-reference/endpoint/get-agent-payment-session.md)读取当前状态。将会话标识与原始支付上下文一起保存；结果未知时不要创建第二个会话。

## 代码示例

### MCP

通过 MCP 让 Agent 调用 Quick Pay 工具。平台需要在 MCP 连接中注入用户授权，并将用户确认、`next_action` 和 Operation 恢复交给受控的 Agent 工具处理。

```markdown theme={null}
处理购买、充值或“用 Clink 支付”请求时：

1. 先调用 `match_products`，展示商户、商品、价格和币种。
2. 取得用户对准确商品或充值金额的确认。
3. 仅在确认后调用一次 `quick_pay`，传入 `confirmed: true`。
4. 按返回的 `next_action` 处理购买授权、支付方式和用户跳转。
5. 结果未知或连接中断时，调用 `get_operation`；有订单 ID 时再调用 `get_clink_order`。
6. 只报告服务端返回的实际支付和订单结果。
```

不要把 MCP Token 或支付凭证交给模型；恢复时沿用同一个 Operation 和原始支付事实，不要重复创建支付会话。

### RESTful API

服务端可以直接调用 Agent Payment Session API，保存会话 ID 和原始支付上下文，并使用同一个会话查询状态：

```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();
}
```

如果需要让 Agent 使用 RESTful API，将创建和查询函数封装为受控工具。服务端负责校验用户身份、金额、币种和幂等性，模型不能获取 `platformToken`。


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