跳到主要内容

Payment Links 集成

本篇描述常见的商户服务端集成顺序：创建商品 → 在 GStable 控制台创建收款账户 → 创建支付链接 → 创建支付（收银）会话 → 将托管结账页链接交给付款人。具体字段与校验以 API 文档及文末资源页为准；这里只保留步骤顺序与每一步在做什么。

前置条件​

集成流程概览​

  1. 创建商品 — 准备或复用目录中的商品，供链接与会话的行项目引用（productId）。
  2. 在 GStable 控制台创建收款账户 — 账户不能通过 SDK 创建；请在商户控制台完成开户与配置，并记录 accountId 供接口使用。SDK 中 client.account 仅支持只读列表与详情。
  3. 创建支付链接 — 调用 client.paymentLink.create，传入上述 accountId、结算代币、费模型与行项目等。保存响应中的 linkId（若产品需要，也可使用 linkUrl）。
  4. 创建支付（收银）会话 — 调用 client.checkoutSession.create，按业务组装 账户 / 结算 / 行项目 等。响应中的 paymentUrl 即托管收银地址。
  5. 获取结账页面链接 — 将 paymentUrl 交给前端或通过消息渠道发给客户，引导其打开托管结账页完成支付。

部分场景可能单独使用步骤 3 返回的 linkUrl，部分场景以步骤 4 的 paymentUrl 为准；请按产品与运营约定选型，并保持与参考文档中的载荷一致。

步骤 1 — 创建商品​

const product = await client.product.create({
  // 字段见 API / Products 参考
});
const productId = product.productId;

或复用已有商品：

const { products } = await client.product.list(1, 50);

步骤 2 — 控制台创建账户​

在 GStable 商户控制台 创建并配置 收款账户，记下将用于接口的 accountId。

如需在代码中核对：

const accounts = await client.account.list();

步骤 3 — 创建支付链接​

const link = await client.paymentLink.create({
  // accountId、settlementToken、feeModel、lineItems 等 — 见 Payment links 参考
});
// 保存 link.linkId；若流程需要链接入口，可使用 link.linkUrl

步骤 4 — 创建收银会话​

const session = await client.checkoutSession.create({
  // accountId、settlementToken、lineItems 等 — 见 Checkout sessions 参考
});
const checkoutPageUrl = session.paymentUrl;

步骤 5 — 结账页面链接​

将 checkoutPageUrl（即 session.paymentUrl）用于重定向、短信/邮件发送等，让客户进入托管结账完成支付。

可选 — 链接后续运营​

目标SDK
暂停新收款client.paymentLink.disable(linkId)
恢复收款client.paymentLink.enable(linkId)
全量更新配置/行项目client.paymentLink.update({ ... })
查看当前配置client.paymentLink.detail(linkId)
运营后台列表client.paymentLink.list(page, size)

可选 — 支付完成之后​

通过 Webhook 或 回跳参数 获取 session id 后，可用 client.checkoutSession.detail(sessionId) 及按状态的列表接口做对账与运营排队，参见 Webhooks 与 Checkout sessions。

运维建议​

  • 重试 — 按平台说明安全重试；仅在 API 明确支持时为对应操作传入幂等字段。
  • 批量读商品 — product.listByIds 可能省略未知 id，请在界面与任务中处理部分结果。
  • 错误 — 按需映射 GStableError / GStableProductError；见 错误码。

延伸阅读​