Checkout Sessions（收银会话）

使用 Checkout Session 资源创建返回 paymentUrl 的托管收银流程，查询会话详情，并按业务状态分页列表。行项目可引用目录商品或 one-time 内联商品信息。

访问收银会话 API

所有收银会话相关操作都通过 GStableClient 实例上的 client.checkoutSession 完成。

错误处理

失败时抛出 GStableError 或其子类。当行项目为 itemType: 'product' 且触发目录侧业务规则时，可能出现 GStableProductError（业务码 100301–100306）。

import { GStableClient, GStableProductError } from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY! });

try {
  const session = await client.checkoutSession.create({
    accountId: 'acc_xxx',
    settlementToken: 'polygon::usdc',
    lineItems: [
      { itemType: 'product', productId: 'prod_xxx', quantity: 1, unitPrice: 5_000_000 },
    ],
    feeModel: 1,
  });
} catch (error) {
  if (error instanceof GStableProductError) {
    console.error(`Product Error [${error.code}]: ${error.message}`);
  }
}

TypeScript 类型

为会话载荷、行项目、详情包装与分页列表提供类型定义，可从包根路径导入。

核心类型

• CheckoutSession — create / detail 返回的会话实体（sessionId、paymentUrl、status、lineItems、signedOnce、expirationTime 等，以 API 为准）。
• CheckoutSessionStatus — 会话生命周期状态。
• CheckoutSessionFeeModel — 手续费承担方（1 商户、2 付款人）。
• SessionDetail — detail 的包装：{ session: CheckoutSession, transaction?: SessionTransaction }（transaction 形状以 API 类型为准）。

请求体

• CreateCheckoutSessionBody — create 的载荷（账户、结算代币、行项目、可选跳转、邮箱策略、费模型、过期时间、元数据）。
• CheckoutLineItemInput — product 与 one_time 的可辨识联合。
• OneTimeProductDataInput — one_time 行中 productData 的内联商品元数据。

响应包装

• CheckoutSessionListData — 分页容器（total、page、size、**sessions: SessionListEntry[]）。
• SessionListEntry — 各状态列表接口中的行结构。
• OperationSuccess — cancel 等变更成功时的返回类型。

import type {
  CheckoutSession,
  CheckoutSessionStatus,
  CheckoutSessionFeeModel,
  CreateCheckoutSessionBody,
  CheckoutLineItemInput,
  OneTimeProductDataInput,
  SessionDetail,
  SessionTransaction,
  CheckoutSessionListData,
  SessionListEntry,
  OperationSuccess,
} from 'gstable-js';

---

create

创建托管 Checkout Session，返回 paymentUrl 与会话元数据。

client.checkoutSession.create(body)

参数

名称	类型	必填	说明
body	CreateCheckoutSessionBody	是	见下表。

CreateCheckoutSessionBody：

字段	类型	必填	说明
accountId	string	是	收款账户。
settlementToken	string	是	结算代币 id。
lineItems	CheckoutLineItemInput[]	是	product 或 one_time 行。
successUrl	string	否	支付完成后跳转。
payerEmailRequired	number	否	1 = 必填，0 = 可选（API 语义）。
feeModel	CheckoutSessionFeeModel (1 | 2)	否	省略时按 API 默认为商户承担。
expirationTime	number	否	Unix 秒；API 有最小时长等约束（如 1800s）。
metadata	Record<string, unknown>	否	不透明元数据，原样回传。

CheckoutLineItemInput：

• itemType: 'product' — productId、quantity、unitPrice（微单位）。
• itemType: 'one_time' — quantity、unitPrice、productData（OneTimeProductDataInput：productName，可选 description / imageUrl / attributes）。

返回值

Promise<CheckoutSession> — 含 sessionId、paymentUrl、status、lineItems、signedOnce、expirationTime 等。

示例

import { GStableClient } from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY! });

const session = await client.checkoutSession.create({
  accountId: 'acc_xxx',
  settlementToken: 'polygon::usdc',
  lineItems: [
    {
      itemType: 'product',
      productId: 'prod_xxx',
      quantity: 1,
      unitPrice: 5_000_000,
    },
  ],
  feeModel: 1,
});

console.log(session.sessionId, session.paymentUrl);

---

cancel

当 signedOnce === 0 时，取消 initialized 会话（按平台规则）。

client.checkoutSession.cancel(sessionId)

参数

名称	类型	必填	说明
sessionId	string	是	Checkout session id。

返回值

Promise<OperationSuccess>

示例

await client.checkoutSession.cancel('sess_xxx');

---

detail

加载会话及可选的链上交易摘要（覆盖由托管收银或 payment link 创建的会话）。

client.checkoutSession.detail(sessionId)

参数

名称	类型	必填	说明
sessionId	string	是	Session id。

返回值

Promise<SessionDetail> — { session: CheckoutSession, transaction?: SessionTransaction }。

示例

const { session, transaction } = await client.checkoutSession.detail('sess_xxx');
console.log(session.status, transaction?.orderId);

---

listAll

client.checkoutSession.listAll(page, size)

参数

名称	类型	必填	说明
page	number	是	从 1 开始的页码。
size	number	是	每页条数。

返回值

Promise<CheckoutSessionListData> — { total, page, size, sessions: SessionListEntry[] }。

示例

const page1 = await client.checkoutSession.listAll(1, 20);
console.log(page1.sessions.length);

---

listPaid

client.checkoutSession.listPaid(page, size)

参数

与 listAll 相同：page、size。

返回值

Promise<CheckoutSessionListData>

示例

const paid = await client.checkoutSession.listPaid(1, 20);

---

listSettling

client.checkoutSession.listSettling(page, size)

参数

page、size。

返回值

Promise<CheckoutSessionListData>

示例

const rows = await client.checkoutSession.listSettling(1, 20);

---

listCompleted

client.checkoutSession.listCompleted(page, size)

参数

page、size。

返回值

Promise<CheckoutSessionListData>

---

listCancelled

client.checkoutSession.listCancelled(page, size)

参数

page、size。

返回值

Promise<CheckoutSessionListData>

---

listSettlementPending

client.checkoutSession.listSettlementPending(page, size)

参数

page、size。

返回值

Promise<CheckoutSessionListData>

示例

const pending = await client.checkoutSession.listSettlementPending(1, 50);