> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Session

> Create a new payment session.

Returns minimal identifiers needed for polling.

**Authentication:** API Key (Bearer token)



## OpenAPI

````yaml /openapi.json post /v1/sessions
openapi: 3.1.0
info:
  title: Maven API
  description: >-
    Voice payment infrastructure — collect credit card payments securely over
    phone calls.
  version: 1.0.0
servers: []
security: []
paths:
  /v1/sessions:
    post:
      tags:
        - Public API (v1)
        - Sessions
      summary: Create Session
      description: |-
        Create a new payment session.

        Returns minimal identifiers needed for polling.

        **Authentication:** API Key (Bearer token)
      operationId: create_session_v1_sessions_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - API Key: []
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
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
          description: Amount in dollars (e.g. 150.00; must be > 0 for charge mode)
        mode:
          $ref: '#/components/schemas/PaymentMode'
          description: 'Payment mode: ''charge'' or ''tokenize'''
        gateway:
          $ref: '#/components/schemas/Gateway'
          description: 'Payment gateway: ''stripe'', ''authorizenet'', ''braintree'', or ''shift4'''
        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
        billing_address:
          anyOf:
            - $ref: '#/components/schemas/BillingAddress'
            - type: 'null'
          title: Billing Address
          description: >-
            Cardholder billing address. When provided, forwarded to the
            processor's billTo block so AVS can return a real match code instead
            of 'U' (unavailable). Authorize.net only today; ignored for other
            gateways.
      type: object
      required:
        - project
        - caller
        - amount
        - mode
        - gateway
      title: SessionCreate
      description: Request to create a payment session.
    SessionCreateResponse:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Session UUID
        status:
          type: string
          title: Status
          description: Session status
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
          description: IVR phone number to call
        sip_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Uri
          description: Twilio SIP domain for SIP calls
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
      type: object
      required:
        - session_id
        - status
        - created_at
      title: SessionCreateResponse
      description: Minimal response after creating a session.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PaymentMode:
      type: string
      enum:
        - charge
        - tokenize
      title: PaymentMode
      description: Payment mode.
    Gateway:
      type: string
      enum:
        - stripe
        - authorizenet
        - braintree
        - shift4
      title: Gateway
      description: Payment gateway.
    BillingAddress:
      properties:
        street:
          type: string
          minLength: 1
          maxLength: 60
          title: Street
          description: Street address line 1
        city:
          type: string
          minLength: 1
          maxLength: 40
          title: City
          description: City
        state:
          type: string
          minLength: 2
          maxLength: 40
          title: State
          description: State / region (2-letter code for US)
        zip:
          type: string
          minLength: 3
          maxLength: 20
          title: Zip
          description: Postal code (5 or 9 digits for US)
        country:
          anyOf:
            - type: string
              minLength: 2
              maxLength: 60
            - type: 'null'
          title: Country
          default: US
          description: ISO-3166-1 alpha-2 country code; defaults to 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. Always pass the cardholder's billing address (the one on file
        with the card issuer), not shipping — AVS only matches against billing.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    API Key:
      type: http
      description: 'Enter your API key: mvn_test_xxx or mvn_live_xxx'
      scheme: bearer

````