Maven Public API (v1) API

openapi: 3.2.0
info:
  title: Maven Public API (v1) API
  description: Voice payment infrastructure — collect credit card payments securely over phone calls.
  version: 1.0.0
tags:
- name: Public API (v1)
paths:
  /v1/auth/check:
    get:
      tags:
      - Public API (v1)
      summary: Check Auth
      description: 'Check if API key is valid.


        Use this to verify your API key is working correctly.


        **Authentication:** API Key (Bearer token)'
      operationId: check_auth_v1_auth_check_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthCheckResponse'
      security:
      - API Key: []
  /v1/projects:
    get:
      tags:
      - Public API (v1)
      summary: List Projects
      description: 'List all projects for this organization.


        **Authentication:** API Key (Bearer token)'
      operationId: list_projects_v1_projects_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key: []
  /v1/sessions:
    post:
      tags:
      - Public API (v1)
      summary: Create Session
      description: 'Create a new payment session.


        Returns minimal identifiers needed for polling.


        Pass `?response_status=200` if your platform does not accept HTTP 201.


        **Authentication:** API Key (Bearer token)'
      operationId: create_session_v1_sessions_post
      security:
      - API Key: []
      parameters:
      - name: response_status
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Override the HTTP status code (e.g. 200). Some voice platforms only accept 200 as success.
          title: Response Status
        description: Override the HTTP status code (e.g. 200). Some voice platforms only accept 200 as success.
      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'
    get:
      tags:
      - Public API (v1)
      summary: Get Session By Caller
      description: 'Get the most recent session for a phone number.


        Returns the most recent active session, or falls back to the latest terminal session.


        **Authentication:** API Key (Bearer token)'
      operationId: get_session_by_caller_v1_sessions_get
      security:
      - API Key: []
      parameters:
      - name: caller
        in: query
        required: true
        schema:
          type: string
          description: Phone number in E.164 format
          title: Caller
        description: Phone number in E.164 format
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionGetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/sessions/{session_id}:
    get:
      tags:
      - Public API (v1)
      summary: Get Session
      description: 'Get session details by ID.


        Returns full session details including status, payment info, and processor details.


        **Authentication:** API Key (Bearer token)'
      operationId: get_session_v1_sessions__session_id__get
      security:
      - API Key: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionGetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/sessions/{session_id}/stream:
    get:
      tags:
      - Public API (v1)
      summary: Stream Session
      description: 'Stream session status updates via Server-Sent Events.


        Sends an initial event immediately, then pushes updates whenever

        the status changes (~1 s poll interval). The stream closes

        automatically on truly terminal statuses (payment-success,

        expired, cancelled, abandoned) or client disconnect.'
      operationId: stream_session_v1_sessions__session_id__stream_get
      security:
      - API Key: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/sessions/{session_id}/cancel:
    post:
      tags:
      - Public API (v1)
      summary: Cancel Session
      description: 'Cancel a pending session.


        Only sessions in PENDING or COLLECTING status can be cancelled.


        **Authentication:** API Key (Bearer token)'
      operationId: cancel_session_v1_sessions__session_id__cancel_post
      security:
      - API Key: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AuthCheckResponse:
      properties:
        authenticated:
          type: boolean
          title: Authenticated
        org_id:
          type: string
          title: Org Id
        mode:
          type: string
          title: Mode
        message:
          type: string
          title: Message
      type: object
      required:
      - authenticated
      - org_id
      - mode
      - message
      title: AuthCheckResponse
      description: Response for auth check endpoint.
    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.


        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
    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: '#/components/schemas/PaymentMode'
          description: 'Payment mode: ''charge'' or ''tokenize'''
        gateway:
          $ref: '#/components/schemas/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: '#/components/schemas/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
      title: SessionCreate
      description: Request to create a payment session.
    SessionGetResponse:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Session UUID
        status:
          type: string
          title: Status
          description: Session status
        is_terminal:
          type: boolean
          title: Is Terminal
          description: Whether the session has reached a final state
        processor:
          anyOf:
          - $ref: '#/components/schemas/Processor'
          - type: 'null'
          description: Payment processor details
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
          description: Error details when status is payment-failed
        amount:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
          description: Amount to charge
        currency:
          type: string
          title: Currency
          description: Currency code
        mode:
          type: string
          title: Mode
          description: Payment mode
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Charge description
        caller:
          anyOf:
          - type: string
          - type: 'null'
          title: Caller
          description: Phone number in E.164 format (voice sessions). Null for chat/widget sessions, which have no caller.
        project_slug:
          type: string
          title: Project Slug
          description: Project slug
        gateway:
          type: string
          title: Gateway
          description: Payment gateway
        callback:
          anyOf:
          - type: string
          - type: 'null'
          title: Callback
          description: Callback phone number
        memory:
          anyOf:
          - type: string
          - type: 'null'
          title: Memory
          description: Call context passed back on transfer
        transfer_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Transfer Status
          description: Outcome of post-payment transfer-back dial
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: When the session expires if unused
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When the session reached a terminal state
      type: object
      required:
      - session_id
      - status
      - is_terminal
      - amount
      - currency
      - mode
      - project_slug
      - gateway
      - created_at
      - updated_at
      title: SessionGetResponse
      description: Full response for session details (GET endpoint).
    Gateway:
      type: string
      enum:
      - stripe
      - authorizenet
      - braintree
      - shift4
      - fiserv
      - jpmorgan
      - webhook
      - nmi
      - qualpay
      - clover
      title: Gateway
      description: Payment gateway.
    Processor:
      properties:
        card_brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Brand
          description: Card brand (visa, mastercard, etc.)
        card_last4:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Last4
          description: Last 4 digits of the card
        receipt_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Receipt Url
          description: Stripe hosted receipt URL
        stripe_charge_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Stripe Charge Id
          description: Stripe Charge ID
        stripe_payment_intent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Stripe Payment Intent Id
          description: Stripe PaymentIntent ID
        payment_method_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Method Id
          description: Stripe PaymentMethod ID (tokenize mode, on connected account)
        stripe_customer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Stripe Customer Id
          description: Stripe Customer ID on connected account (tokenize mode)
        authnet_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Transaction Id
          description: Authorize.net Transaction ID
        authnet_auth_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Auth Code
          description: Authorize.net Authorization Code
        authnet_response_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Response Code
          description: Authorize.net response code (1=Approved, 2=Declined, 3=Error, 4=Held)
        authnet_avs_result_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Avs Result Code
          description: Authorize.net AVS (Address Verification) result code
        authnet_cvv_result_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Cvv Result Code
          description: Authorize.net CVV match result code
        authnet_cavv_result_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Cavv Result Code
          description: Authorize.net CAVV (3D Secure) result code
        authnet_network_trans_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Network Trans Id
          description: Card network transaction ID (Visa/Mastercard) for card-on-file flows
        authnet_capture_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Capture Status
          description: '''captured'' (auto) or ''authorized'' (auth-only, awaiting manual capture)'
        authnet_customer_profile_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Customer Profile Id
          description: Authorize.net CIM Customer Profile ID
        authnet_payment_profile_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Authnet Payment Profile Id
          description: Authorize.net CIM Payment Profile ID
        braintree_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Braintree Transaction Id
          description: Braintree Transaction ID
        braintree_customer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Braintree Customer Id
          description: Braintree Customer ID (tokenize mode)
        braintree_payment_method_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Braintree Payment Method Token
          description: Braintree Payment Method Token (tokenize mode)
        shift4_charge_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Shift4 Charge Id
          description: Shift4 Charge ID
        shift4_customer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Shift4 Customer Id
          description: Shift4 Customer ID (tokenize mode)
        shift4_card_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Shift4 Card Id
          description: Shift4 Card ID (tokenize mode)
        fiserv_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Fiserv Transaction Id
          description: Fiserv ipgTransactionId
        fiserv_order_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Fiserv Order Id
          description: Fiserv orderId
        fiserv_payment_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Fiserv Payment Token
          description: Fiserv reusable paymentToken value
        fiserv_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Fiserv State
          description: Fiserv transactionState (CAPTURED or AUTHORIZED)
        jpmorgan_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Jpmorgan Transaction Id
          description: J.P. Morgan transactionId
        jpmorgan_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Jpmorgan State
          description: J.P. Morgan transactionState (CLOSED = captured)
        jpmorgan_consumer_profile_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Jpmorgan Consumer Profile Id
          description: J.P. Morgan consumerProfileId (tokenize mode)
        jpmorgan_payment_method_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Jpmorgan Payment Method Id
          description: J.P. Morgan paymentMethodId within the consumer profile (tokenize mode)
        jpmorgan_payment_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Jpmorgan Payment Token
          description: J.P. Morgan Safetech network token (tokenize mode, reusable as accountNumber)
        webhook_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Transaction Id
          description: Transaction ID returned by the customer's forwarding endpoint
        webhook_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Token
          description: Token returned by the customer's forwarding endpoint (tokenize mode)
        nmi_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Nmi Transaction Id
          description: NMI transaction ID
        nmi_customer_vault_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Nmi Customer Vault Id
          description: NMI Customer Vault ID (tokenize mode)
        qualpay_pg_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Qualpay Pg Id
          description: Qualpay payment gateway ID (pg_id)
        qualpay_card_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Qualpay Card Id
          description: Qualpay tokenized card ID
        clover_charge_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Clover Charge Id
          description: Clover charge ID
        clover_customer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Clover Customer Id
          description: Clover customer ID (tokenize mode)
      type: object
      title: Processor
      description: Payment processor details.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable error message
      type: object
      required:
      - code
      title: ErrorDetail
      description: Error information for failed sessions.
    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.
    PaymentMode:
      type: string
      enum:
      - charge
      - tokenize
      title: PaymentMode
      description: Payment mode.
  securitySchemes:
    API_Key:
      type: http
      description: 'Enter your API key: mvn_test_xxx or mvn_live_xxx'
      scheme: bearer