Payment Links

A payment link is a reusable template: create it once, share the checkoutUrl, and every visitor gets their own checkout session at that link’s amount and settings. Use a link for anything you’d otherwise re-create per customer, a pricing page button, an emailed invoice, a subscription plan.

`paymentLinks.create(params)`

const link = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro plan',
  successUrl: 'https://shop.com/success',
  cancelUrl: 'https://shop.com/cancel',
  webhookUrl: 'https://shop.com/webhooks',
});

console.log(link.checkoutUrl);
// → https://app.agentaos.ai/pay/7rr6S9ml4BMp829wV5WeAA

Parameters

number

required

Amount in currency units, e.g. 29.99. Min 0.01, max 1,000,000.

string

'EUR' or 'USD'. Defaults to your org’s settlement currency.

string

Max 1000 characters.

'one_time' | 'subscription'

default:"one_time"

See One-time vs subscription below.

'month' | 'year'

Required when type: 'subscription', omit otherwise.

string

UUID of a pre-created tax rate.

string

HTTPS only, max 2048 characters.

string

HTTPS only, max 2048 characters.

string

HTTPS only, max 2048 characters. Inherited by checkouts created from this link.

string

ISO 8601. After this instant, new checkouts can’t be created from the link.

object

Max 8KB serialized. Carried onto every checkout created from this link.

CheckoutField[]

Extra fields to collect on the checkout page. Each entry:

Show CheckoutField

string

required

Max 64 characters.

string

required

Max 128 characters.

'text' | 'email' | 'tel' | 'select'

required

boolean

required

string

Max 256 characters.

string[]

For type: 'select' only.

const link = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro plan',
  checkoutFields: [
    { key: 'email', label: 'Work email', type: 'email', required: true },
    { key: 'company', label: 'Company', type: 'text', required: false },
  ],
});

One-time vs subscription

One-time
Subscription

const link = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro plan: lifetime',
  // type defaults to 'one_time'
});

Each checkout is a single payment. This is the default, type and billingInterval don’t need to be set.

const link = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro plan: monthly',
  type: 'subscription',
  billingInterval: 'month', // 'month' | 'year', required
});

A buyer paying this link creates a Subscription that bills every billingInterval going forward. Subscriptions bill through Merchant of Record (card and bank), so this requires a verified account; wallet-only, on-chain accounts can’t create subscription links.

Response

string

Link UUID.

string

number

Currency units.

string

string | null

'active' | 'cancelled'

'mor' | 'crypto'

How this link settles.

'one_time' | 'subscription'

'month' | 'year' | null

null for one-time links.

string

Shareable payment URL.

object

CheckoutField[]

string | null

number

Times this link has been paid.

string | null

string

{
  "id": "7rr6S9ml-...",
  "orgId": "org_...",
  "amount": 29.99,
  "currency": "EUR",
  "description": "Pro plan",
  "status": "active",
  "sellerMode": "mor",
  "type": "one_time",
  "billingInterval": null,
  "checkoutUrl": "https://app.agentaos.ai/pay/7rr6S9ml4BMp829wV5WeAA",
  "metadata": {},
  "checkoutFields": [],
  "webhookUrl": null,
  "successUrl": null,
  "cancelUrl": null,
  "taxRateId": null,
  "paymentCount": 0,
  "expiresAt": null,
  "createdAt": "2026-08-06T02:00:00.000Z",
  "updatedAt": "2026-08-06T02:00:00.000Z"
}

`paymentLinks.retrieve(id)`

const link = await agentaos.paymentLinks.retrieve('7rr6S9ml-...');
console.log(link.paymentCount); // how many times it's been paid

`paymentLinks.list(params?)`

const page = await agentaos.paymentLinks.list({ limit: 20, offset: 0 });

Takes plain ListParams (limit, offset), no status filter. Returns PaginatedList<PaymentLink>, max limit is 100. See Pagination.

`paymentLinks.cancel(id)`

await agentaos.paymentLinks.cancel('7rr6S9ml-...');
// → { success: true }

This is a soft cancel, the link’s status becomes 'cancelled' and it stops accepting new checkouts, but the record and its payment history stay retrievable via retrieve(). It does not affect subscriptions already created from the link.

Next steps

Checkouts

How checkouts.create({ linkId }) inherits a link’s settings.

Subscriptions

Managing subscriptions created from a type: 'subscription' link.

Customers

The buyers who paid your links.

Webhooks

checkout.session.completed fires for every paid link visit.

SDK

CLI

API Reference

`paymentLinks.create(params)`

Parameters

One-time vs subscription

Response

`paymentLinks.retrieve(id)`

`paymentLinks.list(params?)`

`paymentLinks.cancel(id)`

Next steps

Checkouts

Subscriptions

Customers

Webhooks

​paymentLinks.create(params)

​Parameters

​One-time vs subscription

​Response

​paymentLinks.retrieve(id)

​paymentLinks.list(params?)

​paymentLinks.cancel(id)

​Next steps

Checkouts

Subscriptions

Customers

Webhooks

`paymentLinks.create(params)`

Parameters

One-time vs subscription

Response

`paymentLinks.retrieve(id)`

`paymentLinks.list(params?)`

`paymentLinks.cancel(id)`

Next steps