Checkouts

Create a checkout

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.

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

Headers

Idempotency-Keystring

Alternative to the body's idempotencyKey field. The header wins if both are sent.

Request body

linkIdstring uuid

Payment link UUID to create from. Inherits amount, currency, description, taxRateId, and the seller mode. Omit for a standalone checkout.

amountnumber

Required if no linkId.

amountOverridenumber

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.

descriptionstring
taxRateIdstring uuid
dueDatestring date

YYYY-MM-DD. Presentation only, stamped onto the invoice issued for this checkout.

buyerEmailstring email
buyerNamestring
buyerCompanystring
buyerCountrystring

ISO 3166-1 alpha-2, e.g. DE. Drives destination-VAT calculation.

buyerAddressstring
buyerVatstring
webhookUrlstring uri
successUrlstring uri
cancelUrlstring uri
expiresIninteger

Seconds until expiry. Sessions eligible for SEPA bank transfer get a 48-hour window regardless of this value.

metadataobject

Up to 8KB serialized.

supportedNetworksstring[]

CAIP-2 network IDs. Defaults to Base mainnet for crypto-settlement checkouts.

idempotencyKeystring

Also settable via the Idempotency-Key request header (the header wins if both are sent).

Response

Checkout created.

idstring uuid required

Internal checkout UUID.

payment_link_idstring uuid nullable required
org_idstring uuid required
session_idstring required

Public ID, used in the checkout URL and as the path parameter for every other call on this resource.

idempotency_keystring nullable required
amount_overridenumber nullable required

Set only if you passed amount or amountOverride at create.

currencystring required
metadataobject required
webhook_urlstring nullable required
success_urlstring nullable required
cancel_urlstring nullable required
tax_rate_idstring uuid nullable required
supported_networksstring[] required
expires_atstring date-time required
status'open' | 'completed' | 'expired' | 'cancelled' required
created_atstring date-time required
updated_atstring date-time required
seller_mode'mor' | 'crypto' required
environment'test' | 'live' required
checkoutUrlstring required

Send your buyer here. Computed, camelCase.

invoiceIdstring uuid nullable

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

invoiceNumberstring nullable

Changes

No recorded changes to this operation across all 1 revision of this API.