Checkouts

A checkout is one attempt to collect one payment. Create one directly from your backend when you already know the amount, or create one from a payment link to reuse a shared template. Either way you get a checkoutUrl: send your buyer there to pay.

AgentaOS checkout page showing the product, buyer details, destination VAT, and the total due — What the buyer sees at the checkoutUrl. AgentaOS is the merchant of record, so the page collects the buyer's country, calculates VAT, and shows one total.

Create a checkout

SDK
CLI
cURL

import { AgentaOS } from '@agentaos/pay';

const agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!);

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

// Redirect your buyer to pay
res.redirect(checkout.checkoutUrl);

agenta pay checkout --amount 49.99 --currency EUR --description "Order #123"

curl -X POST https://api.agentaos.ai/api/v1/gateway/sessions \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "EUR",
    "description": "Order #123",
    "successUrl": "https://myshop.com/success",
    "cancelUrl": "https://myshop.com/cart",
    "webhookUrl": "https://myshop.com/webhooks"
  }'

Money model

A plain amount is always in currency units: 49.99 means €49.99, never cents. This holds for every create call, payment link, checkout, and invoice amount in the API. The one exception is subscription.unitAmountMinor, which is an integer of the smallest unit (1999 = €19.99). See Subscriptions for why that field is different. Webhook payloads carry amount as a string ("49.99"), since JSON numbers lose trailing zeros.

Create from a payment link

Pass linkId to inherit the link’s amount, currency, description, taxRateId, and URLs. Override anything per-checkout with amountOverride or the other fields.

const checkout = await agentaos.checkouts.create({
  linkId: link.id,
  metadata: { customerId: '12345' },
});

Payment links vs. standalone checkouts: use a payment link for anything reusable or shareable, a subscription plan, a donation button, a link you paste in chat. Use a standalone checkout when your backend already knows the amount and buyer at the moment of creation, like an e-commerce order at cart checkout.

A standalone (linkless) checkout is always a one-time payment, there’s no type field on checkout create. To sell a subscription, create a subscription payment link (type: 'subscription') and the buyer subscribes at the hosted checkout, or spin up a checkout from that link with linkId.

Pre-populate buyer info

If you already know the buyer (from your own account system), pre-fill their details to skip the checkout form:

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

If you don’t pre-populate, the hosted checkout asks the buyer for name and email directly. Company, VAT, and address are optional but recommended: they land on the invoice.

How the buyer pays

The hosted checkout offers card, Apple Pay, and Google Pay through our card processor. Card details are entered directly into the secure card form, never handled by your server or ours.

Don’t trust successUrl as proof of payment. The buyer’s browser might close before the redirect fires. Use webhooks as the source of truth for “did this checkout actually get paid.”

Retrieve a checkout

SDK
CLI
cURL

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

agenta pay get mZrESFyR7RC9RPsJfZCVkg

curl https://api.agentaos.ai/api/v1/gateway/sessions/mZrESFyR7RC9RPsJfZCVkg \
  -H "x-api-key: sk_live_..."

List checkouts

Paginated: every list call returns { items, total, hasMore }.

SDK
CLI
cURL

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

agenta pay list --status completed --limit 10

curl "https://api.agentaos.ai/api/v1/gateway/sessions?status=completed&limit=10" \
  -H "x-api-key: sk_live_..."

Cancel a checkout

SDK
cURL

await agentaos.checkouts.cancel('mZrESFyR7RC9RPsJfZCVkg');

curl -X POST https://api.agentaos.ai/api/v1/gateway/sessions/mZrESFyR7RC9RPsJfZCVkg/cancel \
  -H "x-api-key: sk_live_..."

Cancelling stops the buyer from paying. If a payment already cleared before the cancel call lands, it still completes; cancelling doesn’t reach into the card processor or on-chain state.

Parameters

number

Amount in currency units (e.g. 49.99). Required if no linkId.

string

Create from a payment link template. Inherits its amount, currency, and configuration.

string

default:"org default"

EUR or USD.

string

Shown on the checkout page. Max 1000 characters.

number

Override the link’s amount for this checkout only.

string

Redirect the buyer here after payment. HTTPS only.

string

“Cancel” link on the checkout page. HTTPS only.

string

Server notification URL for payment events. HTTPS only.

string

UUID of a pre-created tax rate.

string

Pre-populate buyer email. Max 320 characters.

string

Pre-populate buyer name. Max 200 characters.

string

Pre-populate company name. Max 200 characters.

string

ISO 3166-1 alpha-2 (e.g. DE).

string

Pre-populate buyer address. Max 500 characters.

string

Pre-populate VAT number (e.g. DE123456789).

string

ISO date (YYYY-MM-DD). Presentation only, stamped onto the invoice once issued.

number

default:"1800"

Seconds until expiry (300 to 86400).

object

Custom key-value data, returned unchanged in webhooks. Max 8KB.

Response

These are the SDK (camelCase) field names; the raw REST response uses snake_case (e.g. session_id, seller_mode).

string

Session UUID.

string

Public session ID, used in the checkout URL.

string

URL to send your buyer to.

string

open, completed, expired, or cancelled.

string

mor (card + bank) or crypto (on-chain). Inherited from the link, or derived from your account for standalone checkouts.

number | null

Amount for this checkout, if overridden.

string

Settlement currency.

string | null

Issued invoice UUID. null until the payment is confirmed.

string | null

Human-readable invoice number, once issued.

string

ISO 8601.

string

ISO 8601.

Next steps

Payment links

Turn a checkout into a reusable, shareable template.

Subscriptions

Paying a subscription-type link at checkout starts a subscription.

Invoices

Every completed checkout issues a VAT-correct invoice.

Webhooks

Verify checkout.session.completed server-side, don’t rely on the redirect.

Getting Started

Build with AI agents

Sell

Merchant of Record

Webhooks

For customers

Legacy

Create a checkout

Money model

Create from a payment link

Pre-populate buyer info

How the buyer pays

Retrieve a checkout

List checkouts

Cancel a checkout

Parameters

Response

Next steps

Payment links

Subscriptions

Invoices

Webhooks

​Create a checkout

​Money model

​Create from a payment link

​Pre-populate buyer info

​How the buyer pays

​Retrieve a checkout

​List checkouts

​Cancel a checkout

​Parameters

​Response

​Next steps

Payment links

Subscriptions

Invoices

Webhooks

Create a checkout

Money model

Create from a payment link

Pre-populate buyer info

How the buyer pays

Retrieve a checkout

List checkouts

Cancel a checkout

Parameters

Response

Next steps