Checkouts

A checkout is a single payment attempt: one amount, one buyer, one checkoutUrl. Create one from your backend when you know the amount at request time (an e-commerce order, an invoice you’re collecting on). For a reusable, shareable URL, use a payment link instead: each visitor to the link gets their own checkout.

A standalone (linkless) checkout is always a one-time payment: checkouts.create() has no type field. To sell a subscription, create a subscription payment link (type: 'subscription') and the buyer subscribes at the hosted checkout, or open a session from that link with checkouts.create({ linkId }).

`checkouts.create(params)`

const checkout = await agentaos.checkouts.create({
  amount: 100.00,
  currency: 'EUR',
  description: 'Order #123',
  successUrl: 'https://shop.com/success',
  cancelUrl: 'https://shop.com/cart',
  webhookUrl: 'https://shop.com/webhooks',
});

res.redirect(checkout.checkoutUrl);

Parameters

number

Amount in currency units, e.g. 49.99. Required if linkId is omitted. Min 0.01, max 1,000,000.

string

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

string

The payment link’s id, a UUID. On the product page this is Copy link ID. It is not the token in the link’s checkoutUrl. The session inherits the link’s amount, currency, and description. Omit for a standalone checkout.

number

When creating from a linkId, override the link’s amount for this session only. Min 0.01, max 1,000,000.

string

Shown on the checkout page. Max 1000 characters.

string

UUID of a pre-created tax rate.

string

Redirect target after payment. HTTPS only, max 2048 characters.

string

Target for the checkout page’s “cancel” link. HTTPS only, max 2048 characters.

string

Where AgentaOS POSTs this checkout’s checkout.session.completed event, instead of your account’s webhook URL. AgentaOS signs it with your account’s signing secret. HTTPS only, max 2048 characters. See Webhooks.

number

default:"1800"

Seconds until the session expires. Range 300 to 86400.

string

YYYY-MM-DD. Presentation only, stamped onto the invoice issued for this session once payment completes. Never affects the money path.

string[]

CAIP-2 network IDs, e.g. ['eip155:8453']. Defaults to Base mainnet. Only relevant for on-chain (crypto) settlement.

object

Arbitrary key-value data, returned on the session and on the checkout.session.completed event. Max 8KB serialized. Use camelCase keys: webhooks.verify() camelCases them, so user_id comes back as userId. A subscription’s renewal events do not carry it: see Event order for subscriptions.

Pre-populate buyer info

Skip the checkout form’s fields by pre-filling what you already know:

const checkout = await agentaos.checkouts.create({
  amount: 100.00,
  currency: 'EUR',
  buyerEmail: 'john@example.com',
  buyerName: 'John Doe',
  buyerCompany: 'Acme Corp',
  buyerCountry: 'DE',
  buyerVat: 'DE123456789',
  buyerAddress: '123 Main St, Berlin',
});

string

Max 320 characters.

string

Max 200 characters.

string

Max 200 characters.

string

ISO 3166-1 alpha-2, e.g. 'DE'. Max 2 characters.

string

Max 500 characters.

string

Max 20 characters, e.g. 'DE123456789'.

Company, VAT, and address are optional but recommended: they appear on the invoice AgentaOS issues for EU VAT compliance. If you skip buyer fields entirely, the checkout page collects name and email itself before payment.

Response

string

Session UUID.

string

Public session ID, embedded in checkoutUrl.

string | null

Set when created from a linkId; null for a standalone checkout.

string

Your organization’s UUID.

string

URL to send your human customer to.

'open' | 'completed' | 'expired' | 'cancelled'

Current session status.

'mor' | 'crypto'

How this session settles. Resolved server-side, see the note above.

number | null

The amount for this session (currency units), or null if unset.

string

Settlement currency.

object

Whatever you passed in metadata.

string | null

Set once an invoice is issued for this session; null until then.

string | null

Human-readable invoice number, e.g. 'INV-2026-0001'.

string

ISO 8601.

string

ISO 8601.

string

ISO 8601.

{
  "id": "a1b2c3d4-...",
  "paymentLinkId": null,
  "orgId": "b7e2a1c4-...",
  "sessionId": "mZrESFyR7RC9RPsJfZCVkg",
  "checkoutUrl": "https://app.agentaos.ai/checkout/mZrESFyR7RC9RPsJfZCVkg",
  "status": "open",
  "sellerMode": "mor",
  "amountOverride": 100.00,
  "currency": "EUR",
  "metadata": {},
  "successUrl": "https://shop.com/success",
  "cancelUrl": "https://shop.com/cart",
  "invoiceId": null,
  "invoiceNumber": null,
  "expiresAt": "2026-08-06T02:30:00.000Z",
  "createdAt": "2026-08-06T02:00:00.000Z",
  "updatedAt": "2026-08-06T02:00:00.000Z"
}

`checkouts.retrieve(sessionId)`

const checkout = await agentaos.checkouts.retrieve('mZrESFyR7RC9RPsJfZCVkg');
console.log(checkout.status); // 'open' | 'completed' | 'expired' | 'cancelled'

Returns the same shape as create(). Poll this as a fallback if your webhook endpoint is ever unreachable, see Webhooks.

`checkouts.list(params?)`

const page = await agentaos.checkouts.list({
  status: 'completed',
  limit: 10,
  offset: 0,
});
console.log(page.items, page.total, page.hasMore);

'open' | 'completed' | 'expired' | 'cancelled'

Filter by status. Omit to list all statuses.

number

default:"20"

Max 100.

number

default:"0"

Returns PaginatedList<Checkout> ({ items, total, hasMore }), see Pagination.

`checkouts.cancel(sessionId)`

await agentaos.checkouts.cancel('mZrESFyR7RC9RPsJfZCVkg');
// → { success: true }

Canceling prevents the customer from paying through that session. A payment already in flight when you cancel (card authorized, on-chain broadcast) can still complete: cancel changes the status and does not stop a running transaction.

Next steps

Payment links

Reusable templates. Each visitor gets their own checkout.

Webhooks

Get notified server-side when a checkout completes.

Invoices

Every completed checkout issues an invoice you can pull by invoiceId.

Errors

What create() throws on bad params, and how retries work.

SDK

CLI

API Reference

`checkouts.create(params)`

Parameters

Pre-populate buyer info

Response

`checkouts.retrieve(sessionId)`

`checkouts.list(params?)`

`checkouts.cancel(sessionId)`

Next steps

Payment links

Webhooks

Invoices

Errors

​checkouts.create(params)

​Parameters

​Pre-populate buyer info

​Response

​checkouts.retrieve(sessionId)

​checkouts.list(params?)

​checkouts.cancel(sessionId)

​Next steps

Payment links

Webhooks

Invoices

Errors

`checkouts.create(params)`

Parameters

Pre-populate buyer info

Response

`checkouts.retrieve(sessionId)`

`checkouts.list(params?)`

`checkouts.cancel(sessionId)`

Next steps