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

# List payments

> 
Retrieve a paginated list of payments for your organization.

**Use Cases:**
- Track commission-eligible payments
- Export payment data for accounting
- Display payment history in dashboards

**Filtering:**
- Filter by status (succeeded, pending, failed, refunded)
- Filter by lead
- Filter by date range
  

Retrieve a paginated list of payments for your organization.

**Use Cases:**

* Track commission-eligible payments
* Export payment data for accounting
* Display payment history in dashboards

**Filtering:**

* Filter by status (succeeded, pending, failed, refunded)
* Filter by lead
* Filter by date range


## OpenAPI

````yaml openapi.json GET /v1/payments
openapi: 3.1.0
info:
  contact:
    email: support@aura-app.ai
    name: Aura Support
  description: >-
    # Aura Partner Integrations API


    > **Alpha Release** - This API is under active development. Endpoints,
    request/response schemas, and behaviors may change without prior notice. We
    recommend pinning to specific response fields you need and handling unknown
    fields gracefully.


    Enterprise REST API for external partner integrations including

    commission platforms, external mobile apps, and client booking widgets.


    ## MCP Connector


    Aura also exposes a **Model Context Protocol** server at `/mcp` so AI

    assistants (Claude, ChatGPT) can answer questions about a user's own sales
    data.

    If you are building an assistant integration rather than a server-to-server
    one,

    that is almost certainly the surface you want — it is task-shaped ("prep me
    for

    my next call") rather than resource-shaped, and it handles auth per-user.


    Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server;
    discover it

    from `/.well-known/oauth-protected-resource`. Setup guide:

    https://docs.api.aura-app.ai/mcp-connector


    ## Authentication


    Authenticated endpoints support two authentication methods:


    **1. API Key (for partners and integrations):**

    ```

    Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx

    ```

    Get your API key from the Aura dashboard at Settings > API Keys.


    **2. Clerk JWT (for mobile and web apps):**

    ```

    Authorization: Bearer <clerk_jwt_token>

    ```

    Use Clerk's authentication SDK to obtain a JWT token with org claims.


    ## Rate Limiting


    - **Per API Key:** 100 requests/minute

    - **Per Organization:** 1000 requests/minute


    Rate limit headers are included in all responses:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets


    These counters are held per serving instance, so under concurrency the

    effective ceiling is higher than the number above and the headers describe
    one

    instance's view rather than a global total. Treat a 429 as backpressure to
    obey

    and pace your client to the documented rate — but do not rely on us to
    reject

    your 101st request, and do not derive a global remaining-quota figure from
    the

    headers. The limit may become globally enforced without notice, so a client

    that stays within it will not be affected when that happens.


    ## Pagination


    List endpoints support cursor-based pagination:

    - `limit`: Number of results per page (default: 50, max: 100)

    - `cursor`: Opaque cursor for next page


    ## Error Handling


    All errors follow a standard format:


    ```json

    {
      "success": false,
      "error": "Error message",
      "code": "ERROR_CODE"
    }

    ```


    Common HTTP status codes:

    - **400** Bad Request - Invalid input (`VALIDATION_ERROR`)

    - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`)

    - **402** Payment Required - The key is valid, but the organization's
    subscription is not active (`PAYMENT_REQUIRED`). Every authenticated
    endpoint can return this. Retrying will not help until the account's payment
    method is updated in Aura; surface it to the account owner rather than
    treating it as an auth failure.

    - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`)

    - **404** Not Found - Resource not found (`NOT_FOUND`)

    - **409** Conflict - Resource state prevents the operation (`CONFLICT`)

    - **413** Payload Too Large - Request body exceeds 256KB
    (`PAYLOAD_TOO_LARGE`)

    - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`)

    - **500** Internal Server Error - Server error (`INTERNAL_ERROR`)


    ## Webhooks


    Subscribe to real-time events using the Webhooks API. All webhook payloads

    are signed with HMAC-SHA256 for security verification.


    Delivery is at-least-once. Every payload carries an `idempotency_key` that

    is stable across retries of the same event, so you can enforce exactly-once

    with a `(subscription_id, idempotency_key)` unique constraint on your side.


    For full documentation, visit
    [docs.aura-app.ai/api](https://docs.aura-app.ai/api)
  license:
    name: Proprietary
  title: Aura Partner Integrations API
  version: 1.0.0-alpha
servers:
  - description: Production
    url: https://api.aura-app.ai
  - description: Staging
    url: https://staging-api.aura-app.ai
  - description: Local Development
    url: http://localhost:3001
security:
  - bearerAuth: []
tags:
  - description: Lead management operations
    name: Leads
  - description: Call booking and management
    name: Calls
  - description: Booking link configuration (read-only)
    name: Booking Links
  - description: Product catalog (read-only)
    name: Products
  - description: Payment tracking (read-only)
    name: Payments
  - description: Public booking creation
    name: Bookings
  - description: Real-time event subscriptions and webhook management
    name: Webhooks
  - description: >-
      Team member information for commission attribution. **Alpha** - schema may
      change without notice.
    name: Team (Alpha)
  - description: >-
      Dashboard analytics, lead source attribution, and objection analysis.
      **Alpha** - schema may change without notice.
    name: Analytics (Alpha)
  - description: System endpoints (health checks)
    name: System
paths:
  /v1/payments:
    get:
      tags:
        - Payments
      summary: List payments
      description: |-

        Retrieve a paginated list of payments for your organization.

        **Use Cases:**
        - Track commission-eligible payments
        - Export payment data for accounting
        - Display payment history in dashboards

        **Filtering:**
        - Filter by status (succeeded, pending, failed, refunded)
        - Filter by lead
        - Filter by date range
          
      parameters:
        - description: Number of results per page (1-100, values outside clamp)
          in: query
          name: limit
          required: false
          schema:
            description: Number of results per page (1-100, values outside clamp)
            example: 50
            type: integer
        - description: Cursor for pagination
          in: query
          name: cursor
          required: false
          schema:
            description: Cursor for pagination
            type: string
        - description: >-
            Keep payments with this status: succeeded, pending, failed or
            refunded. succeeded also matches paid, verified and completed, the
            spellings payment providers use for settled money.
          in: query
          name: status
          required: false
          schema:
            description: >-
              Keep payments with this status: succeeded, pending, failed or
              refunded. succeeded also matches paid, verified and completed, the
              spellings payment providers use for settled money.
            example: succeeded
            type: string
        - description: Filter by lead ID
          in: query
          name: lead_id
          required: false
          schema:
            description: Filter by lead ID
            type: string
        - description: >-
            Keep payments on or after this date: an ISO 8601 date (read as UTC)
            or a timestamp with a zone.
          in: query
          name: from_date
          required: false
          schema:
            description: >-
              Keep payments on or after this date: an ISO 8601 date (read as
              UTC) or a timestamp with a zone.
            example: '2026-09-21'
            type: string
        - description: >-
            Keep payments on or before this date. A date with no time includes
            that whole day.
          in: query
          name: to_date
          required: false
          schema:
            description: >-
              Keep payments on or before this date. A date with no time includes
              that whole day.
            example: '2026-10-21'
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPaymentsResponse'
          description: Successfully retrieved payments
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: Request validation failed
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid or missing API key
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: The organization's subscription is not active
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: The API key does not have the required scope
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: >-
            The request exceeded its processing time limit. Check the outcome
            before retrying a write
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: The request body exceeds 256KB
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: Rate limit exceeded. Wait before retrying
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            X-RateLimit-Reset:
              description: Window reset as a Unix timestamp
              schema:
                type: string
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: >-
            Unexpected server failure. Include the request identifier when
            contacting support
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
      security:
        - bearerAuth: []
components:
  schemas:
    PaginatedPaymentsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Payment'
          type: array
        filters:
          $ref: '#/components/schemas/AppliedPaymentFilters'
        pagination:
          properties:
            has_more:
              type: boolean
            next_cursor:
              nullable: true
              type: string
          required:
            - next_cursor
            - has_more
          type: object
      required:
        - data
        - pagination
      type: object
    MiddlewareErrorResponse:
      properties:
        code:
          type: string
        error:
          type: string
        requestId:
          type: string
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
        - code
      type: object
    ErrorResponse:
      properties:
        code:
          description: Error code for programmatic handling
          example: NOT_FOUND
          type: string
        error:
          description: Human-readable error message
          example: Lead not found
          type: string
        requestId:
          description: Request ID for support debugging
          example: req_abc123
          type: string
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
        - code
      type: object
    Payment:
      properties:
        amount:
          description: Payment amount (in dollars with decimals)
          example: 5000
          type: number
        call_id:
          description: Associated call ID
          nullable: true
          type: string
        created_at:
          description: Creation timestamp
          format: date-time
          type: string
        currency:
          description: Currency code
          example: usd
          type: string
        customer_email:
          description: Customer email
          nullable: true
          type: string
        customer_name:
          description: Customer name
          nullable: true
          type: string
        id:
          description: Unique identifier
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        lead_id:
          description: Associated lead ID
          nullable: true
          type: string
        match_candidates:
          $ref: '#/components/schemas/PaymentMatchCandidates'
        match_confidence:
          description: Match confidence score 0.00-1.00
          nullable: true
          type: number
        matched_by:
          description: How the payment was matched (email_exact, email+amount, etc.)
          nullable: true
          type: string
        matched_product_id:
          description: Matched Aura product ID
          nullable: true
          type: string
        organization_id:
          description: Organization ID
          type: string
        payment_date:
          description: Payment date
          format: date-time
          type: string
        provider:
          description: Payment provider (e.g., stripe)
          example: stripe
          type: string
        provider_customer_id:
          description: Customer ID assigned by the payment provider. Null when unavailable.
          nullable: true
          type: string
        provider_payment_id:
          description: Payment ID from provider
          example: pi_xxxxx
          type: string
        provider_refund_id:
          description: >-
            Latest provider refund ID, or a stable source-event identity when
            the provider supplies none. Ablefy uses ablefy_revoke: followed by
            its order ID. Null when unavailable.
          nullable: true
          type: string
        refund_reason:
          description: Refund reason from Stripe
          nullable: true
          type: string
        refund_status:
          description: Refund status (partial, full, or null)
          nullable: true
          type: string
        refunded_amount:
          description: Total refunded amount
          nullable: true
          type: number
        refunded_at:
          description: Timestamp of most recent refund
          format: date-time
          nullable: true
          type: string
        status:
          description: Payment status (succeeded, pending, failed, refunded)
          example: succeeded
          type: string
        stripe_charge_id:
          description: Stripe charge ID (ch_*)
          nullable: true
          type: string
        stripe_customer_id:
          deprecated: true
          description: >-
            Deprecated alias of provider_customer_id. Contains the same
            provider-neutral value.
          nullable: true
          type: string
        stripe_product_id:
          description: Stripe Product ID (prod_*)
          nullable: true
          type: string
        stripe_refund_id:
          deprecated: true
          description: >-
            Deprecated alias of provider_refund_id. Contains the same
            provider-neutral value.
          nullable: true
          type: string
        stripe_subscription_id:
          description: Stripe subscription ID (sub_*)
          nullable: true
          type: string
        verification_status:
          description: Payment verification status (unverified, confirmed, unmatched)
          example: confirmed
          nullable: true
          type: string
        verified_at:
          description: When the payment was verified
          format: date-time
          nullable: true
          type: string
      required:
        - id
        - organization_id
        - provider
        - provider_payment_id
        - amount
        - currency
        - status
        - customer_email
        - customer_name
        - lead_id
        - call_id
        - payment_date
        - created_at
        - verification_status
        - verified_at
        - stripe_charge_id
        - provider_customer_id
        - stripe_customer_id
        - stripe_subscription_id
        - matched_by
        - match_confidence
        - match_candidates
        - refund_status
        - refunded_amount
        - refunded_at
        - provider_refund_id
        - stripe_refund_id
        - refund_reason
        - stripe_product_id
        - matched_product_id
      type: object
    AppliedPaymentFilters:
      description: >-
        The filters the server applied, as resolved values. Check it when a page
        is empty to tell no matches from a filter you did not mean.
      properties:
        from_date:
          description: Start of the payment-date window as applied, or null.
          example: '2026-09-21T00:00:00.000Z'
          nullable: true
          type: string
        lead_id:
          description: The lead filter as sent, or null.
          nullable: true
          type: string
        statuses:
          description: >-
            Every status the filter matched. succeeded expands to the spellings
            providers use for settled money.
          example:
            - succeeded
            - paid
            - verified
            - completed
          items:
            type: string
          nullable: true
          type: array
        to_date:
          description: >-
            End of the payment-date window as applied. A plain date covers the
            whole day.
          nullable: true
          type: string
      required:
        - from_date
        - to_date
        - statuses
        - lead_id
      type: object
    PaymentMatchCandidates:
      description: >-
        Top candidates the matching pipeline considered for this payment,
        ordered by score (highest first). Null when the payment was
        deterministically matched. See the PaymentMatchCandidate schema for the
        per-candidate shape.
      items:
        $ref: '#/components/schemas/PaymentMatchCandidate'
      nullable: true
      type: array
    PaymentMatchCandidate:
      anyOf:
        - $ref: '#/components/schemas/LeadMatchCandidate'
        - $ref: '#/components/schemas/CallMatchCandidate'
    LeadMatchCandidate:
      additionalProperties:
        nullable: true
      properties:
        confidence:
          description: Match confidence 0-1. Higher is a better match.
          example: 0.7
          type: number
        email:
          description: Candidate lead's email, as matched against.
          nullable: true
          type: string
        lead_id:
          description: Candidate lead ID.
          type: string
        name:
          description: Candidate lead's full name.
          nullable: true
          type: string
        reason:
          description: How the candidate was found, e.g. 'email_exact', 'name_fuzzy'.
          example: email_exact
          type: string
      required:
        - lead_id
        - email
        - name
        - confidence
        - reason
      type: object
    CallMatchCandidate:
      additionalProperties:
        nullable: true
      properties:
        call_id:
          description: Candidate call ID.
          type: string
        confidence:
          description: Match confidence 0-1.
          type: number
        expected_deal_value:
          description: Expected deal value on the call, in dollars.
          nullable: true
          type: number
        lead_email:
          description: The lead's email.
          type: string
        lead_id:
          description: The call's lead.
          type: string
        match_reasons:
          description: Signals that made this call a candidate.
          items:
            type: string
          type: array
        product_id:
          description: Product discussed on the call.
          nullable: true
          type: string
        scheduled_at:
          description: When the call was booked.
          type: string
      required:
        - call_id
        - lead_id
        - lead_email
        - scheduled_at
        - product_id
        - expected_deal_value
        - confidence
        - match_reasons
      type: object

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.