> ## 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.

# Get billing payment

> Retrieve one payment and the wallet entries created by its settlement, return or refund. Uses the requested billing snapshot when supplied.

Retrieve one payment and the wallet entries created by its settlement, return or refund. Uses the requested billing snapshot when supplied. 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/{id}
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/{id}:
    get:
      tags:
        - Billing
      summary: Get billing payment
      description: >-
        Retrieve one payment and the wallet entries created by its settlement,
        return or refund. Uses the requested billing snapshot when supplied. 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: getBillingPayment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
          description: id
        - 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:
                    $ref: '#/components/schemas/BillingPayment'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
                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
          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/record_synthetic" \
              --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/record_synthetic', 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/record_synthetic", {
              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
    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.