PaymentLinkCreateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentaos-ai/json-schema/agentaos-ai-payment-link-create-request-schema.json",
  "title": "PaymentLinkCreateRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentaos-ai-payment-links-api-openapi.yml#/components/schemas/PaymentLinkCreateRequest",
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 1000000,
      "description": "Amount in currency units, e.g. 49.99."
    },
    "currency": {
      "type": "string",
      "enum": [
        "EUR",
        "USD",
        "EURC",
        "EURe",
        "USDC"
      ],
      "description": "Defaults to your org's settlement currency. A fiat code is mapped to your org's default settlement token internally; the link stores the resolved token."
    },
    "description": {
      "type": "string",
      "maxLength": 1000
    },
    "name": {
      "type": "string",
      "maxLength": 120,
      "description": "Product name, for the catalog-style link surfaces. Separate from `description`."
    },
    "imageUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "HTTPS only."
    },
    "type": {
      "type": "string",
      "enum": [
        "one_time",
        "subscription"
      ],
      "default": "one_time",
      "description": "A `subscription` link requires `billingInterval` and settles on the card/bank rail (Merchant of Record); it can't be a crypto-settlement link."
    },
    "billingInterval": {
      "type": "string",
      "enum": [
        "month",
        "year"
      ],
      "description": "Required when `type` is `subscription`, must be omitted for `one_time`."
    },
    "trialPeriodDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 730,
      "description": "Free-trial length in days. Subscription links only. The buyer's card is saved with nothing due today; the first charge happens when the trial ends."
    },
    "trialAmount": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0.01,
      "maximum": 1000000,
      "description": "Price of the trial period in currency units, e.g. `1.00`. Only with `trialPeriodDays`. Omit it, or send `null`, for a free trial."
    },
    "maxUses": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000,
      "description": "1 for single-use, N for a limited quantity, omitted for unlimited."
    },
    "taxRateId": {
      "type": "string",
      "format": "uuid",
      "description": "Must belong to your organization."
    },
    "checkoutFields": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CheckoutField"
      }
    },
    "webhookUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "successUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "cancelUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "description": "Arbitrary key-value data, returned unchanged on webhooks. Up to 8KB serialized."
    },
    "supportedNetworks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "CAIP-2 network IDs (e.g. eip155:8453), for crypto-settlement links. Ignored (and taken from your key's configuration instead) if your API key is scoped to specific networks."
    }
  },
  "required": [
    "amount"
  ],
  "$defs": {
    "CheckoutField": {
      "type": "object",
      "description": "An extra field collected at checkout.",
      "properties": {
        "key": {
          "type": "string",
          "maxLength": 64
        },
        "label": {
          "type": "string",
          "maxLength": 128
        },
        "type": {
          "type": "string",
          "enum": [
            "text",
            "email",
            "tel",
            "select"
          ]
        },
        "required": {
          "type": "boolean"
        },
        "placeholder": {
          "type": "string",
          "maxLength": 256
        },
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "For `type: select` only."
        }
      },
      "required": [
        "key",
        "label",
        "type",
        "required"
      ]
    }
  }
}