Checkouts

A checkout is one attempt to collect one payment. Each time a buyer opens a product’s buyer link, AgentaOS creates a new checkout for that buyer. You can also create a checkout from your server when your app already knows who the buyer is. In both cases the buyer pays on the same hosted page at https://app.agentaos.ai/…. The Checkouts tab on the Products page lists every checkout with its status: Open, Completed, or Expired.

The buyer’s checkout

The hosted checkout has two steps. The order summary stays on the left: the product, the subtotal, the tax, and the total due. Under the summary, the page states Sold by AgentaOS, merchant of record.

Step 1: Your details

The hosted checkout's Your details step for Plan A at 10 euros plus 24 percent tax, with email, full name, country, the Add VAT ID link, the discount code field, and Continue to payment — The Your details step. The country sets the tax, and a business buyer can add a VAT ID.

The buyer fills in:

Email, required. The receipt goes to this address.
Full name, marked Optional.
Country, required. The hint under it reads “Used to calculate tax on this purchase.” After the buyer picks a country, the hint shows the new total, such as “Total updates to €12.40 including tax.” For a country outside the scope of VAT, it reads “No tax for this country. Total stays the list price.”
Buying for a business? Add VAT ID, a link that opens the VAT ID field. A valid EU VAT ID from another EU country is checked live, and reverse charge (0% VAT) applies only after that check passes.
Discount code, optional. See Discount codes.

If the product has custom checkout fields, they appear under Asked by followed by your business name. The buyer then clicks Continue to payment.

Step 2: Review & pay

The hosted checkout's Review and pay step with Paying as, the Card and Bank transfer options, the card form, and the Pay 12.40 euros button — The Review & pay step. The order summary on the left states Sold by AgentaOS, merchant of record.

The top of the step shows Paying as with the buyer’s email and the total. The buyer can open it to check the country, VAT ID, and tax, or click Edit details to go back. Under Card details, the payment form offers Card and, for EUR payments, Bank transfer. The buyer clicks Pay followed by the amount. Apple Pay and Google Pay appear above the form on devices that support them. The buyer types card details into the secure card form; your server and ours never receive them. After the payment clears, the buyer gets a receipt by email. If the product has a Success URL, the checkout sends the buyer there.

Test mode

A test-mode checkout shows a banner at the top: Test payment · 4242 4242 4242 4242 · any expiry · any CVC. Click the card number to copy it, then paste it into the card field. See Test mode and testing.

Create a checkout from your server

Sharing the buyer link is enough for most sales. Create a checkout from your server when:

The buyer is logged in to your app, and you must know which of your users paid.
You want to attach your own data, such as a user ID or an order number, with metadata. The data comes back in the webhook.
You already have the buyer’s email or country and want to fill them in.

Pass the product’s ID as linkId. On the product page, open Building this into your site? and click Copy ID.

SDK
cURL

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

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

const checkout = await agentaos.checkouts.create({
  linkId: 'link-uuid',
  buyerEmail: 'buyer@example.com',
  metadata: { userId: 'user_123' },
});

res.redirect(checkout.checkoutUrl);

curl -X POST https://api.agentaos.ai/api/v1/gateway/sessions \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "linkId": "link-uuid",
    "buyerEmail": "buyer@example.com",
    "metadata": { "userId": "user_123" }
  }'

A checkout created from a product takes the product’s amount, currency, description, and URLs. Set amountOverride to charge a different amount on this checkout only.

Do not treat the Success URL redirect as proof of payment. The buyer can close the browser before the redirect. Use webhooks or the checkout’s status to confirm the payment.

Create a checkout without a product

When your server knows the amount, you can create a checkout without a product. This checkout is always a one-time payment. To sell a subscription, use a subscription product and pass its linkId.

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

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

Fill in the buyer’s details

const checkout = await agentaos.checkouts.create({
  linkId: 'link-uuid',
  buyerEmail: 'buyer@example.com',
  buyerName: 'Jane Doe',
  buyerCompany: 'Acme GmbH',
  buyerCountry: 'DE',
  buyerVat: 'DE123456789',
  buyerAddress: 'Hauptstrasse 1, Berlin',
});

The company, VAT number, and address are printed on the invoice. The buyer cannot change a field you fill in: the checkout marks it Set by followed by your business name. A field you leave out stays editable. If you do not set buyerCountry, the buyer picks the country, and that choice sets the VAT.

Retrieve, list, and cancel

SDK
CLI
cURL

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

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

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

agenta pay get mZrESFyR7RC9RPsJfZCVkg
agenta pay list --status completed --limit 10

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

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

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

An open checkout expires after expiresIn seconds, from 300 to 86400. Without it, a card checkout lasts 24 hours, an EUR checkout that offers bank transfer 48 hours, and a stablecoin checkout 30 minutes. At the deadline, a card payment not yet completed is stopped and the buyer sees that the checkout has expired. A bank transfer the buyer chose before the deadline is the exception: its details stay valid and the checkout completes when the money arrives, up to 30 days later. You hear about it from checkout.session.bank_transfer_pending. Cancelling stops a payment that is not yet complete. If the buyer already paid, the cancel answers 409 with code: "session_already_paid" and you receive checkout.session.completed for that payment. Money sent after a cancel is not booked to you and is not returned automatically: write to us and we refund it to the buyer. To make a checkout card-only, send paymentMethods: ["card"]. Without it, an EUR checkout also offers bank transfer; every other currency is card only. The buyer’s email is required on every card and bank-transfer checkout, because we send the receipt and invoice. If you create a checkout without buyerEmail, the checkout page asks the buyer for it. The full parameter and response reference is in Checkouts (SDK) and agenta pay.

Money model

A plain amount is in currency units (49.99 means €49.99), and a field whose name ends in Minor is an integer in minor units. The full rules are in the money model.

Next steps

Products

Create the product a checkout sells.

Invoices

The invoice every checkout issues.

Embedded checkout

Show the checkout on your own page.

Webhooks

Confirm the payment on your server.

Getting started

Grow

Build with AI agents

Integrations

Sell

Platforms

Merchant of Record

Payouts

Webhooks

For customers

The buyer’s checkout

Step 1: Your details

Step 2: Review & pay

Test mode

Create a checkout from your server

Create a checkout without a product

Fill in the buyer’s details

Retrieve, list, and cancel

Money model

Next steps

Products

Invoices

Embedded checkout

Webhooks

​The buyer’s checkout

​Step 1: Your details

​Step 2: Review & pay

​Test mode

​Create a checkout from your server

​Create a checkout without a product

​Fill in the buyer’s details

​Retrieve, list, and cancel

​Money model

​Next steps

Products

Invoices

Embedded checkout

Webhooks

The buyer’s checkout

Step 1: Your details

Step 2: Review & pay

Test mode

Create a checkout from your server

Create a checkout without a product

Fill in the buyer’s details

Retrieve, list, and cancel

Money model

Next steps