SessionCreate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/trymaven-com/main/json-schema/trymaven-com-session-create-schema.json",
  "title": "SessionCreate",
  "description": "Request to create a payment session.",
  "x-generated": "2026-10-24",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/trymaven-com-openapi.yml#/components/schemas/SessionCreate",
  "properties": {
    "project": {
      "type": "string",
      "title": "Project",
      "description": "Project identifier (UUID or slug)"
    },
    "caller": {
      "type": "string",
      "title": "Caller",
      "description": "Phone number in E.164 format"
    },
    "amount": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0.0
        },
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        }
      ],
      "title": "Amount",
      "description": "Amount in dollars (e.g. 150.00; must be > 0 for charge mode)"
    },
    "mode": {
      "$ref": "#/$defs/PaymentMode",
      "description": "Payment mode: 'charge' or 'tokenize'"
    },
    "gateway": {
      "$ref": "#/$defs/Gateway",
      "description": "Payment gateway: 'stripe', 'authorizenet', 'braintree', 'shift4', 'fiserv', 'jpmorgan', or 'webhook' (forward card to your own endpoint)"
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "title": "Description",
      "description": "Charge description"
    },
    "callback": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 256
        },
        {
          "type": "null"
        }
      ],
      "title": "Callback",
      "description": "Callback phone number or SIP URI for transfer-back"
    },
    "memory": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Memory",
      "description": "Call context passed back on transfer"
    },
    "stripe_account": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^acct_[A-Za-z0-9]+$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Stripe Account",
      "description": "Stripe Platform Mode only: the connected account (acct_...) on YOUR Stripe platform to charge or vault on. Requires your platform API key to be configured on the project."
    },
    "billing_address": {
      "anyOf": [
        {
          "$ref": "#/$defs/BillingAddress"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cardholder billing address. When provided, forwarded to the processor's billTo block so AVS can return a full match. Authorize.net only today; ignored for other gateways."
    }
  },
  "type": "object",
  "required": [
    "project",
    "caller",
    "amount",
    "mode",
    "gateway"
  ],
  "$defs": {
    "BillingAddress": {
      "properties": {
        "street": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1,
          "title": "Street",
          "description": "Street address line 1"
        },
        "city": {
          "type": "string",
          "maxLength": 40,
          "minLength": 1,
          "title": "City",
          "description": "City"
        },
        "state": {
          "type": "string",
          "maxLength": 40,
          "minLength": 2,
          "title": "State",
          "description": "State / region (2-letter code for US)"
        },
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 3,
          "title": "Zip",
          "description": "Postal code (5 or 9 digits for US)"
        },
        "country": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60,
              "minLength": 2
            },
            {
              "type": "null"
            }
          ],
          "title": "Country",
          "description": "ISO-3166-1 alpha-2 country code; defaults to US",
          "default": "US"
        },
        "first_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ],
          "title": "First Name",
          "description": "Cardholder first name; falls back to value collected during card capture"
        },
        "last_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ],
          "title": "Last Name",
          "description": "Cardholder last name; falls back to value collected during card capture"
        }
      },
      "type": "object",
      "required": [
        "street",
        "city",
        "state",
        "zip"
      ],
      "title": "BillingAddress",
      "description": "Cardholder billing address for AVS. Forwarded to the processor's billTo block.\n\nAlways pass the cardholder's *billing* address (the one on file with the card\nissuer), not shipping — AVS only matches against billing."
    },
    "Gateway": {
      "type": "string",
      "enum": [
        "stripe",
        "authorizenet",
        "braintree",
        "shift4",
        "fiserv",
        "jpmorgan",
        "webhook",
        "nmi",
        "qualpay",
        "clover"
      ],
      "title": "Gateway",
      "description": "Payment gateway."
    },
    "PaymentMode": {
      "type": "string",
      "enum": [
        "charge",
        "tokenize"
      ],
      "title": "PaymentMode",
      "description": "Payment mode."
    }
  }
}