CheckoutCreateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentaos-ai/json-schema/agentaos-ai-checkout-create-request-schema.json",
  "title": "CheckoutCreateRequest",
  "description": "Either `linkId` or `amount` is required (amount is required when creating a standalone checkout with no link).",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentaos-ai-checkouts-api-openapi.yml#/components/schemas/CheckoutCreateRequest",
  "type": "object",
  "properties": {
    "linkId": {
      "type": "string",
      "format": "uuid",
      "description": "Payment link UUID to create from. Inherits amount, currency, description, taxRateId, and the seller mode. Omit for a standalone checkout."
    },
    "amount": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 1000000,
      "description": "Required if no linkId."
    },
    "amountOverride": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 1000000,
      "description": "With linkId, overrides the link's amount for this checkout only."
    },
    "currency": {
      "type": "string",
      "enum": [
        "EUR",
        "USD",
        "EURC",
        "EURe",
        "USDC"
      ],
      "description": "Ignored (inherited from the link) when linkId is set."
    },
    "description": {
      "type": "string",
      "maxLength": 1000
    },
    "taxRateId": {
      "type": "string",
      "format": "uuid"
    },
    "dueDate": {
      "type": "string",
      "format": "date",
      "description": "YYYY-MM-DD. Presentation only, stamped onto the invoice issued for this checkout."
    },
    "buyerEmail": {
      "type": "string",
      "format": "email",
      "maxLength": 320
    },
    "buyerName": {
      "type": "string",
      "maxLength": 200
    },
    "buyerCompany": {
      "type": "string",
      "maxLength": 200
    },
    "buyerCountry": {
      "type": "string",
      "maxLength": 2,
      "description": "ISO 3166-1 alpha-2, e.g. DE. Drives destination-VAT calculation."
    },
    "buyerAddress": {
      "type": "string",
      "maxLength": 500
    },
    "buyerVat": {
      "type": "string",
      "maxLength": 20
    },
    "webhookUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "successUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "cancelUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "expiresIn": {
      "type": "integer",
      "minimum": 300,
      "maximum": 86400,
      "default": 86400,
      "description": "Seconds until the checkout expires. Without it: 24 hours for a card checkout, 48 hours for an EUR checkout that offers bank transfer, 30 minutes for a stablecoin checkout. At the deadline a card payment not yet completed is stopped; a bank transfer the buyer chose before it stays valid up to 30 days."
    },
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "card",
          "bank_transfer"
        ]
      },
      "description": "What the checkout offers. `[\"card\"]` makes it card-only. Without it: card, plus bank transfer on EUR. Card must be included; bank transfer is EUR only. An impossible list answers 400 `payment_methods_unavailable`."
    },
    "metadata": {
      "type": "object",
      "description": "Up to 8KB serialized."
    },
    "supportedNetworks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "CAIP-2 network IDs. Defaults to Base mainnet for crypto-settlement checkouts."
    },
    "idempotencyKey": {
      "type": "string",
      "description": "Also settable via the Idempotency-Key request header (the header wins if both are sent)."
    }
  }
}