Payment Links（支付链接）

使用 Payment Link 资源生成可分享给客户的托管收银 URL。可创建固定金额或自定义金额链接，配置行项目（目录商品或用户定价），并在生命周期内进行启用、停用、列表与详情查询。

访问支付链接 API

所有支付链接相关操作都通过 GStableClient 实例上的 client.paymentLink 完成。

错误处理

失败时抛出 GStableError 或其子类。当行项目为 itemType: 'product' 且引用无效或不可用商品时，可能收到 GStableProductError（业务码 100301–100306）。

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

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

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

TypeScript 类型

为支付链接的请求体、行项目与列表响应提供类型定义，可从包根路径导入。

核心类型

• PaymentLink — create/detail 返回的链接对象（id、URL、状态、金额、行项目等，以 API 为准）。
• PaymentLinkType — 'fixed' 与 'custom' 流程区分。
• PaymentLinkFeeModel — 手续费承担方（1 商户、2 付款人）。
• SettlementTokenInfo — 当 API 返回时，链接载荷中的可选结算元数据。

请求体

• CreatePaymentLinkBody — create 的载荷（账户、结算代币、费模型、行项目、可选跳转与文案）。
• UpdatePaymentLinkBody — 全量替换：CreatePaymentLinkBody 全部字段加上 linkId。
• PaymentLinkLineItemInput — product 与 user_priced 的可辨识联合。

响应包装

• PaymentLinkListData — 分页列表容器（links、total、page、size）。
• OperationSuccess — update、enable、disable 等成功信封的返回类型。

import type {
  PaymentLink,
  PaymentLinkType,
  PaymentLinkFeeModel,
  PaymentLinkLineItemInput,
  CreatePaymentLinkBody,
  UpdatePaymentLinkBody,
  PaymentLinkListData,
  OperationSuccess,
  SettlementTokenInfo,
} from 'gstable-js';

---

create

创建 Payment Link（固定金额或自定义金额流程由 linkType 决定）。

client.paymentLink.create(body)

参数

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

CreatePaymentLinkBody：

字段	类型	必填	说明
linkType	PaymentLinkType ('fixed' | 'custom')	是	固定金额与付款人自选金额流程。
linkName	string	是	运营/报表用标签。
accountId	string	是	收款账户 id。
settlementToken	string	是	结算代币 id（如 network::symbol）。
feeModel	PaymentLinkFeeModel (1 | 2)	是	1 = 商户承担手续费，2 = 付款人承担。
lineItems	PaymentLinkLineItemInput[]	是	行项目（商品或用户定价）。
payerEmailRequired	number	否	1 必填邮箱，0 可选（按 API）。
successUrl	string	否	成功后的跳转 URL。
customSuccessText	string	否	自定义文案。
customDisabledText	string	否	链接禁用时的提示。

PaymentLinkLineItemInput（可辨识联合）：

• { itemType: 'product', productId, quantity, unitPrice } — unitPrice 为微单位，> 0。
• { itemType: 'user_priced', productId, quantity, unitPrice? } — unitPrice 可选 / 0 适用于捐赠类流程。

返回值

Promise<PaymentLink> — 含 linkId、linkUrl、lineItems、amount、status、可选 settlementTokenInfo 等。

示例

import { GStableClient } from 'gstable-js';

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

const link = await client.paymentLink.create({
  linkType: 'fixed',
  linkName: 'Starter checkout',
  accountId: 'acc_xxx',
  settlementToken: 'polygon::usdc',
  feeModel: 1,
  lineItems: [
    {
      itemType: 'product',
      productId: 'prod_xxx',
      quantity: 1,
      unitPrice: 10_000_000,
    },
  ],
  payerEmailRequired: 0,
});

console.log(link.linkId, link.linkUrl);

---

update

对已有链接执行全量替换更新。

client.paymentLink.update(body)

参数

名称	类型	必填	说明
body	UpdatePaymentLinkBody	是	在 CreatePaymentLinkBody 基础上增加 linkId。

UpdatePaymentLinkBody： 包含 CreatePaymentLinkBody 全部字段 以及 linkId: string。

返回值

Promise<OperationSuccess>

示例

await client.paymentLink.update({
  linkId: 'link_xxx',
  linkType: 'fixed',
  linkName: 'Starter checkout v2',
  accountId: 'acc_xxx',
  settlementToken: 'polygon::usdc',
  feeModel: 1,
  lineItems: [
    { itemType: 'product', productId: 'prod_xxx', quantity: 1, unitPrice: 12_000_000 },
  ],
});

---

disable

client.paymentLink.disable(linkId)

参数

名称	类型	必填	说明
linkId	string	是	Payment link id。

返回值

Promise<OperationSuccess>

示例

await client.paymentLink.disable('link_xxx');

---

enable

client.paymentLink.enable(linkId)

参数

名称	类型	必填	说明
linkId	string	是	Payment link id。

返回值

Promise<OperationSuccess>

示例

await client.paymentLink.enable('link_xxx');

---

detail

client.paymentLink.detail(linkId)

参数

名称	类型	必填	说明
linkId	string	是	Payment link id。

返回值

Promise<PaymentLink>

示例

const link = await client.paymentLink.detail('link_xxx');
console.log(link.status, link.amount);

---

list

client.paymentLink.list(page, size)

参数

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

返回值

Promise<PaymentLinkListData> — { links, total, page, size }。

示例

const { links, total } = await client.paymentLink.list(1, 20);
console.log(total, links[0]?.linkId);