支付宝收款 (Payments)

当 Agent 需要向用户收款时，它会在对话里放出一张支付宝 (Alipay) 收款卡片；SDK 负责把卡片渲染出来，并在用户付款后让它自动变成「已支付」。 你不用对接支付宝网关、不用管签名与回调——收款单由平台按 Agent 所有者配置的连接器发起，SDK 只处理「展示卡片」和「感知付款结果」两件事。

前提：Agent 的所有者需先在「应用」里配置好支付宝连接器。走真实交易还是沙箱由服务端的连接器决定，SDK 没有环境参数，同一段代码对两者都适用。

收款是怎么发生的

1. 你像平常一样用 SDK 发消息（见对话 (Chat)）。
2. Agent 需要收款时调用内置的收款工具，平台往对话流里推一条 payment_gate 事件，带着卡片数据（金额、事由、二维码或收银台链接）。
3. 你把卡片渲染给用户：扫码付，或点按钮跳转支付宝收银台。
4. 用户付款后，平台推一条 payment_gate_resolution 事件，卡片随即变成「已支付」。回调延迟时，可以用 client.payments.status(orderId) 主动查询兜底。

卡片的数据结构

PaymentGatePayload：

字段	类型	说明
orderId	string	订单号，结算事件与状态查询的关联键
amountCny	number	金额（人民币元）
reason	string?	收款事由，展示在卡片上
mode	'qr' | 'redirect' | 'auto'	扫码 / 跳收银台 / 自适应（宽屏扫码、窄屏按钮）
qrCode	string?	当面付二维码字符串（qr / auto）
payUrl	string?	收银台 URL（redirect / auto），在新标签页打开
status	'pending' | 'paid' | 'expired' | 'canceled'	推送时的状态，随结算事件或查询更新

⚠️ 不要在渲染时区分「真实还是沙箱」——环境由服务端连接器固定，卡片对两者完全一致。这正是保证真实商户永远不会被错误地走进沙箱代码路径的方式。

在 JS / TS 里处理

import { OpenhexClient, extractPaymentGate, extractPaymentResolution } from '@openhex-ai/agent-sdk';

const client = new OpenhexClient({ apiKey: token, agentId });

for await (const record of client.runTurn('帮我开通一份 VIP 会员')) {
  // 1. 收款卡片
  const gate = extractPaymentGate(record);
  if (gate) {
    renderPayCard(gate); // gate.mode === 'qr' 用 gate.qrCode，否则用 gate.payUrl
    continue;
  }
  // 2. 付款结果
  const settled = extractPaymentResolution(record);
  if (settled?.status === 'paid') markPaid(settled.orderId);
}

只做判断用 isPaymentGate(record)。

主动查询兜底

const { status, amountCny } = await client.payments.status(orderId);
// status: 'pending' | 'paid' | 'expired' | 'canceled'

订单不存在时返回 404 order_not_found。一个订单只用 orderId 定位，不需要传环境。

在 React 里处理

<ChatBox> / <ChatWidget> 自动渲染收款卡片，并在用户付款后自动更新状态（未结算的订单会定期查询），不需要任何接线。卡片文案用 paymentLabels 覆盖，只传你想改的键：

<ChatBox
  agentId="…"
  getToken={getToken}
  paymentLabels={{ title: '支付后继续', payButton: '去支付宝支付', paid: '已到账' }}
/>

文案键	默认值
title	支付后继续
scanHint	打开支付宝扫一扫，完成支付
payButton	去支付宝支付
paid	已支付
expired	支付已过期
canceled	支付已取消
footnote	支付完成后对话自动继续，无需刷新页面

自己画界面时，卡片数据挂在消息的 paymentGate 上，可以直接使用内置的 PaymentGateCard：

import { useOpenhexChat, PaymentGateCard, useInjectStyles } from '@openhex-ai/agent-sdk/react';

function Chat({ getToken }: { getToken: () => Promise<string> }) {
  useInjectStyles(true); // 页面上没有 <ChatBox> 时需要，否则卡片没有样式
  const { messages } = useOpenhexChat({ agentId: '…', getToken });

  return (
    <>
      {messages.map(m =>
        m.paymentGate ? (
          <PaymentGateCard key={m.id} gate={m.paymentGate} labels={{ paid: '已到账' }} />
        ) : (
          <p key={m.id}>{m.text}</p>
        )
      )}
    </>
  );
}

下一步

• 对话 (Chat) — 发消息、流式接收与多轮对话
• 信息收集卡片 — 对话内收集联系人信息
• React 组件 — 组件的全部属性