Skip to main content
Base URL: https://api.agentaos.ai/api/v1 Authentication: x-api-key header with your secret key. 
curl https://api.agentaos.ai/api/v1/gateway/sessions \
  -H "x-api-key: sk_live_your_key_here"
SDK vs REST API: The TypeScript SDK (@agentaos/pay) wraps these endpoints. Method mapping: checkouts.create() → POST /gateway/sessions, checkouts.retrieve() → GET /gateway/sessions/:id. The SDK uses camelCase field names (checkoutUrl), the REST API uses snake_case (checkout_url).

​
Checkout Sessions

​
Create Session

​
amount
number
Amount in currency units (e.g. 49.99). Required if no linkId.
​
currency
string
default:"org default"
EUR or USD. Defaults to org settlement currency.
​
description
string
Shown on checkout page. Max 1000 chars.
​
successUrl
string
Redirect customer here after payment. HTTPS only.
​
cancelUrl
string
“Cancel” link on checkout page. HTTPS only.
​
webhookUrl
string
Server notification URL. HTTPS only.
​
taxRateId
string
UUID of pre-created tax rate.
​
buyerEmail
string
Pre-populate buyer email.
​
buyerName
string
Pre-populate buyer name.
​
buyerCompany
string
Pre-populate company name.
​
buyerCountry
string
ISO 3166-1 alpha-2 (e.g. DE).
​
buyerVat
string
VAT number (e.g. DE123456789).
​
metadata
object
Custom key-value data. Max 8KB.
​
expiresIn
number
default:"1800"
Seconds until expiry (300-86400).
​
linkId
string
Create from a payment link template.
POST /gateway/sessions
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": "Pro Plan",
    "successUrl": "https://shop.com/success",
    "cancelUrl": "https://shop.com/cart",
    "webhookUrl": "https://shop.com/webhooks",
    "buyerEmail": "john@example.com"
  }'

{
  "id": "uuid",
  "session_id": "mZrESFyR7RC9RPsJfZCVkg",
  "checkout_url": "https://app.agentaos.ai/checkout/mZrESFyR7RC9RPsJfZCVkg",
  "status": "open",
  "amount_override": 49.99,
  "currency": "EURe",
  "expires_at": "2026-03-17T02:30:00.000Z",
  "created_at": "2026-03-17T02:00:00.000Z"
}

​
Retrieve Session

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

​
List Sessions

GET /gateway/sessions
curl "https://api.agentaos.ai/api/v1/gateway/sessions?status=completed&limit=10" \
  -H "x-api-key: sk_live_..."
ParameterTypeDescription
statusstringopen, completed, expired, cancelled
limitnumberMax results (1-100, default 10)
offsetnumberPagination offset

​
Cancel Session

POST /gateway/sessions/:sessionId/cancel
curl -X POST https://api.agentaos.ai/api/v1/gateway/sessions/mZrESFyR7RC9RPsJfZCVkg/cancel \
  -H "x-api-key: sk_live_..."
POST /gateway/payment-links
curl -X POST https://api.agentaos.ai/api/v1/gateway/payment-links \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 29.99, "currency": "EUR", "description": "Monthly subscription" }'
GET /gateway/payment-links
curl "https://api.agentaos.ai/api/v1/gateway/payment-links?limit=20" \
  -H "x-api-key: sk_live_..."
DELETE /gateway/payment-links/:id
curl -X DELETE https://api.agentaos.ai/api/v1/gateway/payment-links/uuid \
  -H "x-api-key: sk_live_..."

​
Transactions

​
List Transactions

GET /gateway/all-transactions
curl "https://api.agentaos.ai/api/v1/gateway/all-transactions?direction=inbound&from=2026-03-01&to=2026-03-31" \
  -H "x-api-key: sk_live_..."
ParameterTypeDescription
directionstringall, inbound, outbound
fromstringStart date (ISO 8601)
tostringEnd date (ISO 8601)
limitnumberMax results
offsetnumberPagination offset

​
Invoices

​
List Invoices

GET /gateway/invoices
curl "https://api.agentaos.ai/api/v1/gateway/invoices?from=2026-03-01&to=2026-03-31&status=issued" \
  -H "x-api-key: sk_live_..."

​
Download Invoice PDF

GET /gateway/invoices/:id/pdf
curl https://api.agentaos.ai/api/v1/gateway/invoices/uuid/pdf \
  -H "x-api-key: sk_live_..." \
  -o invoice.pdf

​
Download Monthly Statement

GET /gateway/invoices/statement
curl "https://api.agentaos.ai/api/v1/gateway/invoices/statement?from=2026-03-01&to=2026-03-31" \
  -H "x-api-key: sk_live_..." \
  -o statement.pdf

​
Export CSV

GET /gateway/invoices/export
curl "https://api.agentaos.ai/api/v1/gateway/invoices/export?from=2026-03-01&to=2026-03-31" \
  -H "x-api-key: sk_live_..." \
  -o invoices.csv

​
Void Invoice

POST /gateway/invoices/:id/void
curl -X POST https://api.agentaos.ai/api/v1/gateway/invoices/uuid/void \
  -H "x-api-key: sk_live_..."

​
Errors

{
  "statusCode": 400,
  "message": "amount is required when creating a session without a link"
}
StatusMeaning
400Bad request - invalid parameters
401Unauthorized - invalid or missing API key
403Forbidden - key doesn’t have access
404Not found - resource doesn’t exist
409Conflict - idempotency conflict
429Rate limited (check Retry-After header)
500Server error - retry with backoff

​
Rate Limits

EndpointLimit
POST /gateway/send20/min
All authenticated endpoints100/min
Public endpoints30/min