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, its checkouts.create({ linkId }) call is how each visitor gets their own session.

A standalone (linkless) checkout is always a one-time payment, there’s no type field on checkouts.create(). 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

UUID of an existing payment link to create this session from. The session inherits the link’s amount, currency, description, taxRateId, successUrl, cancelUrl, and webhookUrl, all overridable per-field. 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 the checkout.session.completed event. HTTPS only, max 2048 characters. See Webhooks.

number

default:"1800"

Seconds until the session expires. Range 300–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, round-tripped onto the session and onto the webhook payload. Max 8KB serialized.

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 land directly 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 }

Cancelling prevents the customer from paying through that session. If a payment was already in flight (card authorized, on-chain broadcast) when you cancel, it may still complete, cancel is a status change, not a mid-transaction abort.

Next steps

Payment links

Reusable templates. Each visit calls checkouts.create({ linkId }) under the hood.

Webhooks

Get notified server-side the moment 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