Payment Links

Use the Payment Link resource to build hosted checkout URLs you can share with customers. Create fixed-price or custom-amount links, attach line items (catalog products or user-priced rows), and manage links over their lifecycle (enable, disable, list, and detail).

Accessing payment links

All Payment Link operations are available via the client.paymentLink property on your GStableClient instance.

Error handling

Failures surface as GStableError or a subclass. When a line item uses itemType: 'product', invalid or blocked catalog state may be reported as GStableProductError (business codes 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 support

We provide TypeScript definitions for Payment Link payloads, line items, and list responses. Import them from the package root.

Core types

• PaymentLink — The link object returned by create/detail (ids, URL, status, amounts, line items, and related fields per API).
• PaymentLinkType — 'fixed' vs 'custom' flow discriminator.
• PaymentLinkFeeModel — Who absorbs fees (1 merchant, 2 payer).
• SettlementTokenInfo — Optional settlement metadata on link payloads when the API includes it.

Request bodies

• CreatePaymentLinkBody — Payload for create (account, settlement token, fee model, line items, optional URLs and copy).
• UpdatePaymentLinkBody — Full replacement: all CreatePaymentLinkBody fields plus linkId.
• PaymentLinkLineItemInput — Discriminated union for product vs user_priced rows.

Response wrappers

• PaymentLinkListData — Paginated list container (links, total, page, size).
• OperationSuccess — Returned for update, enable, disable, and similar success envelopes.

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

---

create

Creates a Payment Link (fixed or custom amount flow per linkType).

client.paymentLink.create(body)

Parameters

Name	Type	Required	Description
body	CreatePaymentLinkBody	Yes	See table below.

CreatePaymentLinkBody:

Field	Type	Required	Description
linkType	PaymentLinkType ('fixed' | 'custom')	Yes	Fixed vs payer-chosen amount flows.
linkName	string	Yes	Label for operators / reports.
accountId	string	Yes	Receiving account id.
settlementToken	string	Yes	Settlement token id (e.g. network::symbol).
feeModel	PaymentLinkFeeModel (1 | 2)	Yes	1 = merchant pays fee, 2 = payer pays fee.
lineItems	PaymentLinkLineItemInput[]	Yes	Line items (product or user-priced).
payerEmailRequired	number	No	1 require email, 0 optional (per API).
successUrl	string	No	Redirect after success.
customSuccessText	string	No	Custom copy.
customDisabledText	string	No	When link disabled.

PaymentLinkLineItemInput (discriminated union):

• { itemType: 'product', productId, quantity, unitPrice } — unitPrice micro units, > 0.
• { itemType: 'user_priced', productId, quantity, unitPrice? } — unitPrice optional / 0 for donor-style flows.

Returns

Promise<PaymentLink> — Includes linkId, linkUrl, lineItems, amount, status, optional settlementTokenInfo, etc.

Example

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, // micro-units per API
    },
  ],
  payerEmailRequired: 0,
});

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

---

update

Full replacement update for an existing link.

client.paymentLink.update(body)

Parameters

Name	Type	Required	Description
body	UpdatePaymentLinkBody	Yes	Extends CreatePaymentLinkBody with linkId.

UpdatePaymentLinkBody: all CreatePaymentLinkBody fields plus linkId: string.

Returns

Promise<OperationSuccess>

Example

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)

Parameters

Name	Type	Required	Description
linkId	string	Yes	Payment link id.

Returns

Promise<OperationSuccess>

Example

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

---

enable

client.paymentLink.enable(linkId)

Parameters

Name	Type	Required	Description
linkId	string	Yes	Payment link id.

Returns

Promise<OperationSuccess>

Example

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

---

detail

client.paymentLink.detail(linkId)

Parameters

Name	Type	Required	Description
linkId	string	Yes	Payment link id.

Returns

Promise<PaymentLink>

Example

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

---

list

client.paymentLink.list(page, size)

Parameters

Name	Type	Required	Description
page	number	Yes	1-based page.
size	number	Yes	Page size.

Returns

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

Example

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