Skip to main content

Payment Links integration

This guide walks through a common merchant-backend sequence: create catalog items, configure receiving in the dashboard, create a Payment Link, create a checkout (payment) session, then hand off the hosted checkout URL to the payer. Field-level requirements live in the API reference and the resource pages linked at the end; here we only keep order of operations and what each step is for.

Prerequisites​

Integration sequence​

At a high level the flow is:

  1. Create products — Build or reuse catalog rows (productIds) for your link and session line items.
  2. Create a receiving account in the GStable dashboard — Accounts are not created through the SDK; use the merchant console to add the receiving account and copy its accountId for API calls. The SDK’s client.account namespace is read-only (list/detail).
  3. Create a Payment Link — Call client.paymentLink.create with that accountId, settlement token, fee model, and line items. Keep linkId (and linkUrl if your product uses it) from the response.
  4. Create a payment (checkout) session — Call client.checkoutSession.create with the same kind of account / settlement / line item context your checkout needs. The response includes paymentUrl.
  5. Open the checkout page — Redirect or share paymentUrl to the customer so they complete pay-in on the hosted page.

Some teams use linkUrl from step 3 alone, others rely on paymentUrl from step 4—pick the path your product and operations agreed on, and keep payloads aligned with the references above.

Step 1 — Products​

const product = await client.product.create({
  // Fields per API / Products reference
});
const productId = product.productId;

Or reuse existing catalog rows:

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

Step 2 — Account in the dashboard​

Create and configure the receiving account in the GStable merchant dashboard. Note the accountId you will pass into client.paymentLink.create and client.checkoutSession.create.

To verify from code:

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

Step 3 — Payment Link​

const link = await client.paymentLink.create({
  // accountId, settlementToken, feeModel, lineItems, … — see Payment links reference
});
// Store link.linkId; use link.linkUrl when your flow needs the link-hosted entry point

Step 4 — Checkout session​

const session = await client.checkoutSession.create({
  // accountId, settlementToken, lineItems, … — see Checkout sessions reference
});
const checkoutPageUrl = session.paymentUrl;

Step 5 — Checkout page link​

Send checkoutPageUrl (session.paymentUrl) to your frontend or customer channel (redirect, email, etc.) so they land on hosted checkout.

Optional — Operating the link later​

GoalSDK
Pause new pay-insclient.paymentLink.disable(linkId)
Resumeclient.paymentLink.enable(linkId)
Full metadata / item updatesclient.paymentLink.update({ ... })
Inspect configurationclient.paymentLink.detail(linkId)
Operator list UIclient.paymentLink.list(page, size)

Optional — After payment​

Use webhooks or redirect parameters to receive a session id, then client.checkoutSession.detail(sessionId) (and status-scoped list helpers if you run ops queues) for reconciliation—see Webhooks and Checkout sessions.

Operational tips​

  • Retries — Follow platform guidance; pass idempotency fields only when the API documents them for that operation.
  • Partial catalog reads — product.listByIds may omit unknown ids; handle partial results in your UI.
  • Errors — Map GStableError / GStableProductError as needed; see Error codes.

Further reading​