---
title: "Create a checkout"
method: POST
path: "/gateway/sessions"
tags: ["Checkouts"]
---

# Create a checkout

`POST /gateway/sessions`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/sessions`
- Auth: API key in header `x-api-key`

Creates a checkout session, standalone or built from a payment link with `linkId`. The create and list responses do **not** include a plain `amount`, only `amount_override` (`null` unless you passed one). Call "Retrieve a checkout" for a computed, ready-to-display `amount`. Accepts an `Idempotency-Key` header (wins over a body `idempotencyKey` if both are sent); a repeat call with the same key returns the same checkout instead of creating a second one.

## Headers

- `Idempotency-Key` string

## Request body

- CheckoutCreateRequest: Either `linkId` or `amount` is required (amount is required when creating a standalone checkout with no link).
  - `linkId` string, uuid: Payment link UUID to create from. Inherits amount, currency, description, taxRateId, and the seller mode. Omit for a standalone checkout.
  - `amount` number: Required if no linkId.
  - `amountOverride` number: With linkId, overrides the link's amount for this checkout only.
  - `currency` 'EUR' | 'USD' | 'EURC' | 'EURe' | 'USDC': Ignored (inherited from the link) when linkId is set.
  - `description` string
  - `taxRateId` string, uuid
  - `dueDate` string, date: YYYY-MM-DD. Presentation only, stamped onto the invoice issued for this checkout.
  - `buyerEmail` string, email
  - `buyerName` string
  - `buyerCompany` string
  - `buyerCountry` string: ISO 3166-1 alpha-2, e.g. DE. Drives destination-VAT calculation.
  - `buyerAddress` string
  - `buyerVat` string
  - `webhookUrl` string, uri
  - `successUrl` string, uri
  - `cancelUrl` string, uri
  - `expiresIn` integer: Seconds until expiry. Sessions eligible for SEPA bank transfer get a 48-hour window regardless of this value.
  - `metadata` object: Up to 8KB serialized.
  - `supportedNetworks` string[]: CAIP-2 network IDs. Defaults to Base mainnet for crypto-settlement checkouts.
  - `idempotencyKey` string: Also settable via the Idempotency-Key request header (the header wins if both are sent).

## Response `201`

Checkout created.

- Checkout
  - `id` string, uuid, required: Internal checkout UUID.
  - `payment_link_id` string, uuid, nullable, required
  - `org_id` string, uuid, required
  - `session_id` string, required: Public ID, used in the checkout URL and as the path parameter for every other call on this resource.
  - `idempotency_key` string, nullable, required
  - `amount_override` number, nullable, required: Set only if you passed amount or amountOverride at create.
  - `currency` string, required
  - `metadata` object, required
  - `webhook_url` string, nullable, required
  - `success_url` string, nullable, required
  - `cancel_url` string, nullable, required
  - `tax_rate_id` string, uuid, nullable, required
  - `supported_networks` string[], required
  - `expires_at` string, date-time, required
  - `status` 'open' | 'completed' | 'expired' | 'cancelled', required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `seller_mode` 'mor' | 'crypto', required
  - `environment` 'test' | 'live', required
  - `checkoutUrl` string, required: Send your buyer here. Computed, camelCase.
  - `invoiceId` string, uuid, nullable: Set once an invoice has been issued for this session; null until then.
  - `invoiceNumber` string, nullable

## Other responses

- `400`: A required field is missing, out of range, or the wrong type. `ValidationPipe` also rejects any field not in the documented schema.
- `401`: Missing or invalid `x-api-key`.
- `403`: The key is valid but the resource belongs to a different organization.

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)