Checkout Sessions

Use the Checkout Session resource to create hosted checkout flows that return a paymentUrl, then inspect sessions and list them by operational status. Line items can reference catalog products or one-time product data.

Accessing checkout sessions

All checkout session operations are available via the client.checkoutSession property on your GStableClient instance.

Error handling

Failures surface as GStableError or a subclass. itemType: 'product' lines may trigger GStableProductError when catalog rules fail (business codes 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 support

We provide TypeScript definitions for session payloads, line items, detail wrappers, and paginated lists. Import them from the package root.

Core types

• CheckoutSession — Session entity from create / detail (sessionId, paymentUrl, status, lineItems, signedOnce, expirationTime, and fields per API).
• CheckoutSessionStatus — Session lifecycle status values.
• CheckoutSessionFeeModel — Who absorbs fees (1 merchant, 2 payer).
• SessionDetail — detail response wrapper: { session: CheckoutSession, transaction?: SessionTransaction } (transaction shape per API types).

Request bodies

• CreateCheckoutSessionBody — Payload for create (account, settlement token, line items, optional redirect, email policy, fee model, expiry, metadata).
• CheckoutLineItemInput — Discriminated union for product vs one_time lines.
• OneTimeProductDataInput — Inline product metadata for one_time line productData.

Response wrappers

• CheckoutSessionListData — Paginated list container (total, page, size, **sessions: SessionListEntry[]`).
• SessionListEntry — Row shape used in status-scoped list endpoints.
• OperationSuccess — Returned for cancel and other mutation success envelopes.

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

---

create

Creates a hosted Checkout Session and returns paymentUrl and session metadata.

client.checkoutSession.create(body)

Parameters

Name	Type	Required	Description
body	CreateCheckoutSessionBody	Yes	See table.

CreateCheckoutSessionBody:

Field	Type	Required	Description
accountId	string	Yes	Receiving account.
settlementToken	string	Yes	Settlement token id.
lineItems	CheckoutLineItemInput[]	Yes	product or one_time lines.
successUrl	string	No	Post-payment redirect.
payerEmailRequired	number	No	1 = required, 0 = optional (API semantics).
feeModel	CheckoutSessionFeeModel (1 | 2)	No	Default merchant-absorbed when omitted per API.
expirationTime	number	No	Unix seconds; API enforces minimum span (e.g. 1800s).
metadata	Record<string, unknown>	No	Opaque metadata echoed back.

CheckoutLineItemInput:

• itemType: 'product' — productId, quantity, unitPrice (micro units).
• itemType: 'one_time' — quantity, unitPrice, productData (OneTimeProductDataInput: productName, optional description / imageUrl / attributes).

Returns

Promise<CheckoutSession> — Includes sessionId, paymentUrl, status, lineItems, signedOnce, expirationTime, etc.

Example

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

Cancels an initialized session when signedOnce === 0 (per platform rules).

client.checkoutSession.cancel(sessionId)

Parameters

Name	Type	Required	Description
sessionId	string	Yes	Checkout session id.

Returns

Promise<OperationSuccess>

Example

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

---

detail

Loads session plus optional chain transaction summary (covers sessions created from hosted checkout or payment links).

client.checkoutSession.detail(sessionId)

Parameters

Name	Type	Required	Description
sessionId	string	Yes	Session id.

Returns

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

Example

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

---

listAll

client.checkoutSession.listAll(page, size)

Parameters

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

Returns

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

Example

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

---

listPaid

client.checkoutSession.listPaid(page, size)

Parameters

Same as listAll: page, size.

Returns

Promise<CheckoutSessionListData>

Example

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

---

listSettling

client.checkoutSession.listSettling(page, size)

Parameters

page, size.

Returns

Promise<CheckoutSessionListData>

Example

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

---

listCompleted

client.checkoutSession.listCompleted(page, size)

Parameters

page, size.

Returns

Promise<CheckoutSessionListData>

---

listCancelled

client.checkoutSession.listCancelled(page, size)

Parameters

page, size.

Returns

Promise<CheckoutSessionListData>

---

listSettlementPending

client.checkoutSession.listSettlementPending(page, size)

Parameters

page, size.

Returns

Promise<CheckoutSessionListData>

Example

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