集成工作流

本指南提供了 AI Checkout 流程的分步实现教程。我们假设您正在使用 Node.js 或 TypeScript 构建 Agent 运行时。

准备工作

您需要一个 Web3 库来处理 EIP-712 哈希和签名（如果在服务端测试）或请求签名（如果在客户端）。

npm install ethers
# 或者
npm install viem

第 1 步：获取支付链接 (Fetch Payment Link)

流程始于您的 Agent 识别到一个支付链接 ID（例如 lnk_...）。

const getPaymentLink = async (linkId) => {
  const response = await fetch(`https://api.gstable.io/payment/link/${linkId}`);
  const data = await response.json();
  return data;
};

有关完整字段定义，请参考 API 参考：获取支付链接

{
  "linkId": "lnk_Wch3k5nYWWOvDLFvlwS4tzP6R9rZiQmi",
  "linkVersion": "ver_dB54AvbEnFOSuLeA",
  "merchantId": "f7d65b193454db46fb2d6277e2f5e593bffcf6adde5064a2bb5dee6fd9b0fb7a",
  "aiView": {
    "supportedPaymentTokens": [
      {
        "chainId": "137",
        "tokenAddress": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
        "symbol": "USDC",
        "amountInToken": "3009000", // 3.009 USDC
        "decimals": 6
      }
    ],
    "createPaymentSessionRequirement": {
      "authorizationRequired": true,
      "authorizationSpec": {
        "type": "eip712",
        "domain": { ... },
        "types": { ... }
      }
    }
  }
}

第 2 步：实现授权逻辑

要创建会话，您必须生成签名。我们提供了一个辅助类来构造 EIP-712 载荷。

辅助类：PaymentSessionCreationAuthorizationMessage

将此类复制到您的项目中以处理消息构造。

class PaymentSessionCreationAuthorizationMessage {
  constructor({
    linkId,
    linkVersion,
    merchantId,
    payer,
    paymentChainId,
    paymentToken,
    amount,
    authorizationNonce,
    authorizationExpiresAt,
  }) {
    this.purpose = 'create_payment_session';
    this.linkId = linkId;
    this.linkVersion = linkVersion;
    this.merchantId = merchantId;
    this.payer = payer;
    this.paymentChainId = BigInt(paymentChainId);
    this.paymentToken = paymentToken;
    this.amount = BigInt(amount);
    this.authorizationNonce = authorizationNonce;
    this.authorizationExpiresAt = BigInt(authorizationExpiresAt);
  }

  toMessage() {
    return {
      purpose: this.purpose,
      linkId: this.linkId,
      linkVersion: this.linkVersion,
      merchantId: this.merchantId,
      payer: this.payer,
      paymentChainId: this.paymentChainId.toString(),
      paymentToken: this.paymentToken,
      amount: this.amount.toString(),
      authorizationNonce: this.authorizationNonce,
      authorizationExpiresAt: this.authorizationExpiresAt.toString(),
    };
  }
}

第 3 步：创建支付会话 (Create Payment Session)

一旦用户确认支付意向（例如，“使用 Polygon 上的 USDC 支付”），您的 Agent 将构造载荷并请求签名。

3.1 构造消息

// 1. 生成 Nonce 和过期时间
const nonce = "0x" + require('crypto').randomBytes(32).toString('hex');
const expiresAt = Math.floor(Date.now() / 1000) + 3600; // 1 小时有效期

// 2. 初始化辅助类
const authMsg = new PaymentSessionCreationAuthorizationMessage({
  linkId: "lnk_Wch3k5nYWWOvDLFvlwS4tzP6R9rZiQmi",
  linkVersion: "ver_dB54AvbEnFOSuLeA", // 来自第 1 步的响应
  merchantId: "f7d65b193454db46fb2d6277e2f5e593bffcf6adde5064a2bb5dee6fd9b0fb7a", // 来自第 1 步的响应
  payer: "0x123...", // 用户钱包地址
  paymentChainId: "137", // 用户选择
  paymentToken: "0x3c4...", // 用户选择
  amount: "3009000", // 来自第 1 步的响应 (supportedPaymentTokens)
  authorizationNonce: nonce,
  authorizationExpiresAt: expiresAt
});

3.2 请求用户签名（客户端）

如果您的 Agent 在浏览器环境中运行，请使用用户的 Provider 进行签名。

// 使用 ethers.js v6
const domain = {
  name: "aipay.gstable.io",
  version: "1",
  chainId: 137 // 必须匹配 paymentChainId
};

const types = {
  PaymentSessionCreationAuthorization: [
    { name: "purpose", type: "string" },
    { name: "linkId", type: "string" },
    { name: "merchantId", type: "string" },
    { name: "payer", type: "address" },
    { name: "paymentChainId", type: "uint256" },
    { name: "paymentToken", type: "address" },
    { name: "amount", type: "uint256" },
    { name: "authorizationNonce", type: "bytes32" },
    { name: "authorizationExpiresAt", type: "uint256" }
  ]
};

// 从钱包请求签名
const signature = await signer.signTypedData(domain, types, authMsg.toMessage());

3.3 调用 API

有关完整字段定义，请参考 API 参考：创建会话

发送签名后的载荷以创建会话。

const createSession = async () => {
  const payload = {
    message: authMsg.toMessage(),
    signature: signature
  };

  const response = await fetch('https://api.gstable.io/payment/session/create', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

第 4 步：准备并执行支付 (Prepare & Execute)

创建会话后，流程进入 prepare_payment 阶段。此步骤将锁定最终的交易详情。

辅助类：PreparePaymentAuthorizationMessage

class PreparePaymentAuthorizationMessage {
  constructor({
    sessionId,
    merchantId,
    payer,
    payerEmail,
    paymentChainId,
    paymentToken,
    authorizationNonce,
    authorizationExpiresAt,
  }) {
    this.purpose = 'prepare_payment';
    this.sessionId = sessionId;
    this.merchantId = merchantId;
    this.payer = payer;
    this.paymentChainId = BigInt(paymentChainId);
    this.payerEmail = payerEmail;
    this.paymentToken = paymentToken;
    this.authorizationNonce = authorizationNonce;
    this.authorizationExpiresAt = BigInt(authorizationExpiresAt);
  }

  toMessage() {
    return {
      purpose: this.purpose,
      sessionId: this.sessionId,
      merchantId: this.merchantId,
      payer: this.payer,
      payerEmail: this.payerEmail,
      paymentChainId: this.paymentChainId.toString(),
      paymentToken: this.paymentToken,
      authorizationNonce: this.authorizationNonce,
      authorizationExpiresAt: this.authorizationExpiresAt.toString(),
    };
  }
}

执行流程

有关完整字段定义，请参考 API 参考：准备支付

1. 使用第 3 步返回的 sessionId 构造 PreparePaymentAuthorizationMessage。
2. 再次请求用户签名。
3. 调用 POST /payment/prepare。
4. API 返回 calldata。
5. 您的 Agent 提示用户发送交易：

// 第 5 步：发送交易
const tx = await signer.sendTransaction({
  to: response.data.aiView.paymentExecutionGuide.executionRequest.txRequest.to,
  data: response.data.calldata,
  value: 0
});
console.log("Transaction sent:", tx.hash);