支付会话

Checkout Session 是 GStable 低代码集成的核心。与持久化的 Payment Link 不同，Checkout Session 是一次性的、程序化生成的支付页面。

它非常适合以下场景：

• 电商网站的购物车结账（每次金额不同）。
• 动态定价的服务。
• 需要将支付状态回调（Webhook）与特定用户订单关联的场景。

统一会话管理

虽然 Checkout Session 和 Payment Link 的创建方式不同，但在 GStable 系统内部，它们都会生成一个 Session 对象。本章节后半部分的 查询接口 适用于查询系统内所有的支付会话（无论是由 API 创建还是由 Payment Link 触发）。

核心概念

会话状态 (Status)

支付会话的生命周期状态流转如下：

状态	标识符	描述
初始化	initialized	会话已创建，等待用户支付。
已支付	paid	用户已在链上完成付款，资金已进入智能合约，等待系统结算。
结算中	settling	GStable 正在进行跨链资金路由和结算。
已完成	completed	结算完成，资金已到达商户收款钱包。
结算受阻	settlement_pending	特殊状态。因区块重组等极端情况导致结算延迟，系统已进入自动再结算流程。平台重试机制保证支付幂等性，资金最终会安全结算。
已过期	expired	超过有效期未支付，会话关闭。
已取消	cancelled	商户主动取消了会话。

商品类型 (Item Type)

在创建 Checkout Session 时，支持以下两种商品类型：

类型	标识符	描述
库存商品	product	引用已创建的商品 ID。
一次性商品	one_time	Checkout 专属。无需预先创建商品，直接在请求中定义名称和价格。仅对当前会话有效，不会录入商品库。

---

创建 Checkout Session

POST /session/checkout/create

创建一个指向 GStable 托管收银台的临时会话。

请求参数

参数	类型	必填	描述
accountId	String	✅	收款账户 ID。
settlementToken	String	✅	结算代币 ID（如 polygon::usdc）。
lineItems	Object[]	✅	商品列表。Checkout Session 仅支持 product 和 one_time 类型。
successUrl	String	❌	支付成功后跳转的 URL。
payerEmailRequired	Integer	❌	1 必填邮箱，0 选填。
feeModel	Integer	❌	1 商户承担手续费 (默认)，2 用户承担手续费。
expirationTime	Long	❌	过期时间戳（秒）。默认为当前时间 + 30分钟。最小间隔 1800秒。
metadata	Object	❌	附加数据。用于存储商户系统的内部订单号或其他元数据。

请求示例

{
  "accountId": "acc_example_merchant_02",
  "settlementToken": "polygon::usdc",
  "successUrl": "https://yoursite.com/order/success",
  "payerEmailRequired": 1,
  "feeModel": 1,
  "metadata": {
    "internalOrderId": "ord_8823_xyz"
  },
  "lineItems": [
    {
      "itemType": "product",
      "productId": "prd_IFWvmf2XivVLlu1fTeRP6Q",
      "quantity": 1,
      "unitPrice": 10000000 // 10 USD
    },
    {
      "itemType": "one_time",
      "quantity": 1,
      "unitPrice": 5000000, // 5 USD
      "productData": {
        "productName": "加急处理费",
        "productDescription": "24小时内响应",
        "imageUrl": "https://example.com/service.png",
        "attributes": [
          { "name": "类型", "value": "服务" }
        ]
      }
    }
  ]
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "sessionId": "sess_example_payment_01",
    "sessionType": "chk",
    "businessId": "", // Checkout Session 此字段固定为空
    "businessType": "", // Checkout Session 此字段固定为空
    "clientCode": "clt_l8ZBnpOSV9pVlaLK0dP5jsq5NzfqN3Vc",
    "payer": "", // 初始化时为空
    "payerEmail": "", // 初始化时为空
    "payerEmailRequired": 1,
    "paidToken": "", // 初始化时为空
    "receiptId": "rcpt_txUdSs2ASditQhrr", // 仅支付成功后有意义
    "recipient": "0x1234567890abcdef...", // 对应的收款钱包地址
    "settlementToken": "polygon::usdc",
    "feeModel": 1,
    "amount": 15000000, // 总金额 (Micro-USD)
    "lineItems": {
      "items": [
        {
          "lineItemId": "li_example_item_03",
          "itemType": "product",
          "productId": "prd_IFWvmf2XivVLlu1fTeRP6Q",
          "quantity": 1,
          "unitPrice": 10000000,
          "productData": {
            "productName": "高级会员",
            "productDescription": "解锁所有高级功能",
            "imageUrl": "https://example.com/product.png",
            "attributes": [
              { "name": "时长", "value": "1个月" }
            ]
          }
        },
        {
          "lineItemId": "li_example_item_04",
          "itemType": "one_time",
          "productId": "",
          "quantity": 1,
          "unitPrice": 5000000,
          "productData": {
            "productName": "加急处理费",
            "productDescription": "24小时内响应",
            "imageUrl": "https://example.com/service.png",
            "attributes": [
              { "name": "类型", "value": "服务" }
            ]
          }
        }
      ]
    },
    "expirationTime": 1767343946,
    "successUrl": "https://yoursite.com/order/success",
    "paymentUrl": "https://pay.gstable.io/checkout/sess_example_payment_01",
    "signedOnce": 0, // 是否已签发过支付。已签发的 Session 无法取消
    "initiateTx": "", // 支付发起交易 Hash (初始化时为空)
    "completeTx": "", // 支付完成交易 Hash (初始化时为空)
    "paymentSucceededTime": null,
    "settlementSucceededTime": null,
    "createAt": "2026-01-02 07:52:26",
    "status": "initialized",
    "metadata": {
      "internalOrderId": "ord_8823_xyz"
    }
  }
}

---

取消会话

POST /session/checkout/cancel

仅当会话处于 initialized 状态且未被用户签发支付（signedOnce = 0）时可取消。

请求示例

{
  "sessionId": "sess_example_payment_01"
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

查询支付会话

GStable 提供了一套统一的查询接口，用于获取 Checkout Session 和 Payment Link Session 的详细信息及交易数据。这是商户进行系统对账（Reconciliation）的主要方式。

获取单个会话详情

GET /session/:sessionId

此接口返回会话的完整信息。如果用户已付款，还会包含 transaction 对象，展示链上资金流向。

响应示例 (已支付状态)

{
  "code": 0,
  "message": "success",
  "data": {
    // --- 会话基础信息 (结构同创建接口返回) ---
    "session": {
      "sessionId": "sess_example_payment_01",
      "status": "completed",
      "amount": 15000000,
      "settlementToken": "polygon::usdc",
      "feeModel": 1,
      "metadata": {
        "internalOrderId": "ord_8823_xyz"
      },
      "paymentSucceededTime": "2025-12-25 07:26:35",
      "settlementSucceededTime": "2025-12-25 07:27:10",
      "receiptId": "rcpt_txUdSs2ASditQhrr",
      "payerEmail": "user@example.com",
      // ... 其他字段
    },
    // --- 链上交易详情 (仅已支付/已完成时存在) ---
    "transaction": {
      "orderId": "0x8a7f...", // 链上订单唯一标识
      "channelId": "da1e3483", // 链上支付通道 ID
      "orderType": 7106155,
      "from": "0x...", // 付款人钱包地址
      "to": "0x...", // 商户结算的收款地址
      "metaData": "0x", // 链上元数据
      "totalValue": 15000000, // 用户实际支付总额
      "paymentValue": 15000000, // 订单商品总额 (amount)
      "feeValue": 30000, // 手续费 (Micro-USD)
      "netValue": 14970000, // 商户实收净额 (Micro-USD)
      "sourceTx": "0x...", // 用户付款交易哈希
      "targetTx": "0x...", // 平台结算给商户的交易哈希
      "executeTime": "2025-12-25 07:26:35", // 付款时间
      "finalizeTime": "2025-12-25 07:26:35" // 结算完成时间
    }
  }
}

关于金额计算

• feeModel = 1 (商户付费): netValue = paymentValue - feeValue。
• feeModel = 2 (用户付费): netValue = paymentValue。此时 totalValue 会包含额外的手续费。

批量查询会话

平台提供了以下独立的 API 路径来按状态筛选会话列表。

GET /session/list/all/:page/:size (所有会话) GET /session/list/paid/:page/:size (已支付) GET /session/list/settling/:page/:size (结算中) GET /session/list/completed/:page/:size (已完成) GET /session/list/cancelled/:page/:size (已取消) GET /session/list/settlement/pending/:page/:size (结算受阻)

• :page: 页码，从 1 开始。
• :size: 每页数量，最大 100。

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "size": 10,
    "sessions": [
      {
        // 结构同单个查询接口的 data 部分
        "session": {
          "sessionId": "sess_example_payment_01",
          "status": "completed",
          ...
        },
        "transaction": { ... }
      },
      // ... 更多数据
    ]
  }
}