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

# List billing payments

> Read top-up and contract-funding payment attempts, including pending, failed, settled, returned and refunded states. Pending or failed payments are not spendable credits.

Read top-up and contract-funding payment attempts, including pending, failed, settled, returned and refunded states. Pending or failed payments are not spendable credits. All IDs and cursors must belong to the authorized workspace and environment. Required scope: billing:read. Owner authority is required. Related reads can pin snapshot\_id from billing summary to reconcile the same as-of state; expired snapshots return 410, never a silent refresh.

Examples use synthetic IDs. Replace them with values returned by your environment.


## OpenAPI

````yaml openapi/amlok.json GET /v1/billing/payments
openapi: 3.1.0
info:
  title: AMLOK API
  version: 1.0.0
  description: >-
    AMLOK API: borrower connections, Insights origination, immutable risk
    packages and Signal monitoring. Use your institution-issued API origin.
servers: []
security:
  - BearerAuth: []
paths:
  /v1/billing/payments:
    get:
      tags:
        - Billing
      summary: List billing payments
      description: >-
        Read top-up and contract-funding payment attempts, including pending,
        failed, settled, returned and refunded states. Pending or failed
        payments are not spendable credits. All IDs and cursors must belong to
        the authorized workspace and environment. Required scope: billing:read.
        Owner authority is required. Related reads can pin snapshot_id from
        billing summary to reconcile the same as-of state; expired snapshots
        return 410, never a silent refresh.
      operationId: listBillingPayments
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: cursor
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: limit
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - processing
              - succeeded
              - failed
              - cancelled
              - partially_refunded
              - refunded
              - returned
          description: status
        - name: purpose
          in: query
          required: false
          schema:
            type: string
            enum:
              - initial_funding
              - renewal
              - automatic_top_up
              - manual_top_up
          description: purpose
        - name: created_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            created from. UTC ranges are inclusive from and exclusive to; reject
            to <= from.
        - name: created_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            created to. UTC ranges are inclusive from and exclusive to; reject
            to <= from.
        - name: snapshot_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: snapshot id
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingPayment'
                  meta:
                    $ref: '#/components/schemas/Meta'
                  page:
                    $ref: '#/components/schemas/Page'
                required:
                  - data
                  - meta
                  - page
                additionalProperties: false
              example:
                data:
                  - id: pay_synthetic
                    snapshot_id: snap_synthetic
                    created_at: '2026-11-06T12:00:00Z'
                    updated_at: '2026-11-06T12:00:00Z'
                    status: succeeded
                    purpose: manual_top_up
                    amount: '5000.00'
                    currency: CAD
                    credited_amount: '5000.00'
                    refunded_amount: '0.00'
                    method:
                      type: card
                      label: Visa ending 4242
                    external_reference: PAY-SYNTHETIC-0042
                    settled_at: '2026-11-06T12:00:00Z'
                    failure_reason: null
                    transaction_ids:
                      - txn_funding_synthetic
                    record_version: 1
                meta:
                  request_id: req_synthetic
                  schema_version: 1.0.0
                  environment: sandbox
                page:
                  next_cursor: null
                  has_more: false
                  snapshot_id: snap_synthetic
                  expires_at: '2026-11-06T13:00:00Z'
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '400':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: validation_error
                  message: Validation error.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '401':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: unauthenticated
                  message: Unauthenticated.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '403':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: forbidden
                  message: Forbidden.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '404':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: not_found
                  message: Not found.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '409':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: invalid_state
                  message: Invalid state.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '410':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '429':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: rate_limited
                  message: Rate limited.
                  retryable: true
                  request_id: req_synthetic
                  field: null
          headers:
            Retry-After:
              description: Minimum delay in seconds before retry.
              schema:
                type: integer
                minimum: 0
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '503':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: temporarily_unavailable
                  message: Temporarily unavailable.
                  retryable: true
                  request_id: req_synthetic
                  field: null
          headers:
            Retry-After:
              description: Minimum delay in seconds before retry.
              schema:
                type: integer
                minimum: 0
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |-
            curl --request GET --fail-with-body --max-time 30 \
              "${AMLOK_API_BASE_URL}/v1/billing/payments" \
              --header "Authorization: Bearer ${AMLOK_API_KEY}" \
              --header 'Accept: application/json'
        - lang: Python
          source: >
            import os

            import requests


            headers = {'Accept': 'application/json'}

            headers["Authorization"] = "Bearer " + os.environ["AMLOK_API_KEY"]

            response = requests.request('GET', os.environ["AMLOK_API_BASE_URL"]
            + '/v1/billing/payments', headers=headers, timeout=30,
            allow_redirects=False)

            response.raise_for_status()

            print(response.json())
        - lang: JavaScript
          source: >
            const headers = {"Accept": "application/json"};

            headers.Authorization = `Bearer ${process.env.AMLOK_API_KEY}`;

            const response = await fetch(process.env.AMLOK_API_BASE_URL +
            "/v1/billing/payments", {
              method: "GET", headers, redirect: "error", signal: AbortSignal.timeout(30000)
            });

            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await
            response.text()}`);

            console.log(await response.json());
components:
  schemas:
    BillingPayment:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: >-
            Funding payment or top-up attempt identifier; not a wallet ledger
            ID.
        snapshot_id:
          type: string
          minLength: 1
          description: Billing snapshot used for this representation.
        created_at:
          type: string
          minLength: 1
          format: date-time
          description: UTC time the payment attempt was recorded.
        updated_at:
          type: string
          minLength: 1
          format: date-time
          description: UTC time its state most recently changed.
        status:
          type: string
          enum:
            - pending
            - processing
            - succeeded
            - failed
            - cancelled
            - partially_refunded
            - refunded
            - returned
          description: >-
            Payment lifecycle status; only posted ledger entries change the
            wallet.
        purpose:
          type: string
          enum:
            - initial_funding
            - renewal
            - automatic_top_up
            - manual_top_up
          description: Initial/renewal contract funding or an automatic/manual top-up.
        amount:
          type: string
          minLength: 1
          pattern: ^(?:0|[1-9][0-9]*)\.[0-9]{2}$
          description: >-
            Requested payment amount in CAD major units, as a two-decimal
            string.
        currency:
          const: CAD
          description: >-
            Currency for BillingPayment. Constraints, requiredness and allowed
            values are defined by this schema.
        credited_amount:
          type: string
          minLength: 1
          pattern: ^(?:0|[1-9][0-9]*)\.[0-9]{2}$
          description: >-
            Total credits actually posted for this payment before subsequent
            reversals; zero until credit posting.
        refunded_amount:
          type: string
          minLength: 1
          pattern: ^(?:0|[1-9][0-9]*)\.[0-9]{2}$
          description: Total payment refunds recorded as of this snapshot, in CAD.
        method:
          type: object
          properties:
            type:
              type: string
              enum:
                - card
                - ach
                - bank_transfer
            label:
              type: string
              minLength: 1
              description: >-
                Masked display label only; no card number, routing number, bank
                credentials or payment token.
          required:
            - type
            - label
          additionalProperties: false
          description: >-
            Method for BillingPayment. Constraints, requiredness and allowed
            values are defined by this schema.
        external_reference:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: Non-secret reconciliation reference from the payment system.
        settled_at:
          anyOf:
            - type: string
              minLength: 1
              format: date-time
            - type: 'null'
          description: UTC settlement time; null before settlement or if payment failed.
        failure_reason:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: Human-readable failure or return explanation, when available.
        transaction_ids:
          type: array
          items:
            type: string
            minLength: 1
            description: Opaque ID within the authorized workspace and environment.
          uniqueItems: true
          description: >-
            Immutable wallet entries for credit posting and subsequent
            returns/refunds.
        record_version:
          type: integer
          minimum: 1
          description: >-
            Monotonically increasing version of this resource. Compare with
            event.resource_version; snapshot reads preserve their historical
            version.
      required:
        - id
        - snapshot_id
        - created_at
        - updated_at
        - status
        - purpose
        - amount
        - currency
        - credited_amount
        - refunded_amount
        - method
        - external_reference
        - settled_at
        - failure_reason
        - transaction_ids
        - record_version
      additionalProperties: false
      description: >-
        Read-only payment/funding state as of snapshot_id. Pending, processing,
        failed and cancelled attempts do not increase credits. credited_amount
        is cumulative credit actually posted for this payment; later
        returns/refunds are linked negative transactions, not a rewrite of
        funding history.
      allOf:
        - if:
            properties:
              status:
                enum:
                  - pending
                  - processing
                  - failed
                  - cancelled
          then:
            properties:
              credited_amount:
                const: '0.00'
              settled_at:
                type: 'null'
        - if:
            properties:
              status:
                const: failed
          then:
            properties:
              failure_reason:
                type: string
                minLength: 1
    Meta:
      type: object
      properties:
        request_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        schema_version:
          type: string
          minLength: 1
          description: >-
            Schema version for Meta. Constraints, requiredness and allowed
            values are defined by this schema.
        environment:
          type: string
          enum:
            - sandbox
            - live
          description: >-
            Environment for Meta. Constraints, requiredness and allowed values
            are defined by this schema.
      required:
        - request_id
        - schema_version
        - environment
      additionalProperties: false
    Page:
      type: object
      properties:
        next_cursor:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: >-
            Next cursor for Page. Constraints, requiredness and allowed values
            are defined by this schema.
        has_more:
          type: boolean
          description: >-
            Has more for Page. Constraints, requiredness and allowed values are
            defined by this schema.
        snapshot_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        expires_at:
          type: string
          minLength: 1
          description: >-
            Snapshot expiry. After expiry, respond 410 and restart with a new
            snapshot; never continue on a new snapshot silently.
          format: date-time
      required:
        - next_cursor
        - has_more
        - snapshot_id
        - expires_at
      additionalProperties: false
      description: >-
        Opaque cursor binds filters, authorization and a stable snapshot.
        Expired cursors return 410; never silently restart.
    Error:
      type: object
      properties:
        code:
          type: string
          enum:
            - validation_error
            - unauthenticated
            - forbidden
            - not_found
            - invalid_state
            - idempotency_conflict
            - insufficient_credits
            - precondition_failed
            - cursor_expired
            - rate_limited
            - temporarily_unavailable
            - deal_snapshot_conflict
            - payload_too_large
            - unsupported_media_type
            - document_rejected
            - processing_failed
            - session_expired
            - consent_purpose_missing
            - sandbox_only
            - scenario_not_available
            - idempotency_result_expired
          description: >-
            Code for Error. Constraints, requiredness and allowed values are
            defined by this schema.
        message:
          type: string
          minLength: 1
          description: >-
            Message for Error. Constraints, requiredness and allowed values are
            defined by this schema.
        retryable:
          type: boolean
          description: >-
            Retryable for Error. Constraints, requiredness and allowed values
            are defined by this schema.
        request_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        field:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: >-
            Field for Error. Constraints, requiredness and allowed values are
            defined by this schema.
      required:
        - code
        - message
        - retryable
        - request_id
        - field
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Server-to-server API key bound to exactly one workspace, institution
        tenant and environment. No caller-supplied workspace override is
        accepted. Do not use in public browser code.

````

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