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

# Balance Lookup

> Balance enquiry against a provider's stored value catalog.




## OpenAPI

````yaml POST /stored_value/lookup
openapi: 3.1.0
info:
  version: 1.0.0
  title: Redemptions API
  description: Redemptions API
  summary: Orchestrates redemption lifecycle against external providers.
  contact:
    name: Moment
    url: https://momentco.net
    email: support@momentco.net
  license:
    name: Proprietary
    url: https://momentco.net/api-terms
servers:
  - url: https://api.momentpay.net
security: []
tags:
  - name: Redemptions
    x-displayName: Redemptions
    description: >-
      A `Redemption` represents a stateful aggregate that clients drive from
      `draft` through `reserved` to `confirmed`, with idempotent POST operations
      against external voucher providers.
  - name: Stored Value
    x-displayName: Stored Value
    description: >-
      Stateless stored value queries against providers (balance lookup, voucher
      metadata).
  - name: Discovery
    x-displayName: Discovery
    description: >-
      Static metadata describing the redemption types the API supports, their
      capabilities, and the `source` attributes each requires. Lets headless
      clients discover supported types dynamically.
  - name: Events
    x-displayName: Events
    description: >
      Outbound CloudEvents v1.0 envelopes emitted on every redemption state
      transition. Delivered via change data capture from the `outbox_events`
      collection to downstream consumers. Subscribers should be idempotent on
      event `id` (at least once delivery).
  - name: Redemption Model
    x-displayName: Redemption Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/redemption" />
  - name: Operation Model
    x-displayName: Operation Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/operation" />
  - name: Change Voucher Model
    x-displayName: Change Voucher Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/change_voucher" />
  - name: CloudEvent Model
    x-displayName: CloudEvent Envelope Model
    description: |
      CloudEvents v1.0 envelope used for all outbound redemption events.

      <SchemaDefinition schemaRef="#/components/schemas/cloudevent_envelope" />
  - name: Problem Detail Model
    x-displayName: Problem Detail Model
    description: >
      RFC 9457 problem details. Returned with `Content-Type:
      application/problem+json` on every error response.


      <SchemaDefinition schemaRef="#/components/schemas/problem_detail" />
externalDocs:
  description: Read the full API documentation
  url: https://momentco.net/docs
paths:
  /stored_value/lookup:
    post:
      tags:
        - Stored Value
      summary: Look up stored value balance or metadata
      description: |
        Balance enquiry against a provider's stored value catalog.
      operationId: lookup_stored_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lookup_stored_value_request'
            examples:
              OTT:
                $ref: '#/components/examples/lookup_ott'
              Blu by token:
                $ref: '#/components/examples/lookup_blu_token'
              Blu by serial number:
                $ref: '#/components/examples/lookup_blu_serial'
      responses:
        '200':
          description: Lookup result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lookup_stored_value_response'
              examples:
                OTT:
                  $ref: '#/components/examples/lookup_ott_response'
                Blu by token:
                  $ref: '#/components/examples/lookup_blu_token_response'
                Blu by serial number:
                  $ref: '#/components/examples/lookup_blu_serial_response'
        '400':
          $ref: '#/components/responses/lookup_bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '422':
          $ref: '#/components/responses/operation_not_allowed'
        '500':
          $ref: '#/components/responses/internal_server_error'
      security:
        - bearer_auth: []
components:
  schemas:
    lookup_stored_value_request:
      type: object
      description: Request body for a stateless stored value lookup.
      required:
        - type
        - source
      properties:
        type:
          $ref: '#/components/schemas/type'
        source:
          $ref: '#/components/schemas/lookup_source'
    lookup_stored_value_response:
      type: object
      description: Generic envelope returned by a successful stored value lookup.
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/type'
        balance:
          type: integer
          description: Stored value balance in minor units (cents).
        currency:
          type: string
          minLength: 3
          maxLength: 3
        source:
          $ref: '#/components/schemas/lookup_source'
          description: >-
            Echo of the provider specific source the lookup was performed
            against.
        provider_metadata:
          $ref: '#/components/schemas/lookup_provider_metadata'
        error:
          $ref: '#/components/schemas/operation_error'
      additionalProperties: false
    type:
      title: Redemption Type
      type: string
      description: >
        Namespaced redemption type in `category.type` form. The category selects
        the value class and the suffix selects the specific provider that will
        fulfil the redemption.


        Only the `vouchers` category is available today. Loyalty point
        categories (for example `loyalty_points.skywards`,
        `loyalty_points.ebucks`) are planned.
      enum:
        - vouchers.one_voucher
        - vouchers.ott
        - vouchers.blu
    lookup_source:
      title: Lookup Source
      description: >
        Provider specific source credential object for a stored value lookup.
        The shape is owned by the adapter and selected by the parent `type`
        field.


        `1Voucher` does not expose a stored value lookup and is not represented
        here. A lookup request for `1Voucher` is still validated but returns
        HTTP 422.
      oneOf:
        - title: OTT
          type: object
          required:
            - pin
            - phone_number
          properties:
            pin:
              type: string
              description: Voucher PIN or token. Sensitive value.
            phone_number:
              type: string
              description: Subscriber phone number associated with the voucher.
          additionalProperties: false
        - title: Blu
          type: object
          description: >-
            Provide `token` or `serial_number` (at least one). Serial number
            takes precedence if both are supplied.
          minProperties: 1
          properties:
            token:
              type: string
              description: Blu voucher token or PIN. Sensitive value.
            serial_number:
              type: string
              description: Blu voucher serial number.
          additionalProperties: false
    lookup_provider_metadata:
      type: object
      description: >
        Provider specific result fields returned by a stored value lookup. The
        shape is selected by the parent `provider` field. Only keys returned by
        the upstream provider are present.
      oneOf:
        - title: OTT
          type: object
          required:
            - pin_status
          properties:
            pin_status:
              type: string
              description: Provider reported PIN status (for example `active`).
            denomination:
              type: integer
              description: Face value of the voucher in minor units (cents).
            expires_at:
              type: string
              format: date-time
              description: Voucher expiry, when the provider returns one.
          additionalProperties: false
        - title: Blu
          type: object
          required:
            - voucher_status
          properties:
            serial_number:
              type: string
              description: Blu voucher serial number.
            reference:
              type: string
              description: Blu voucher reference.
            expires_at:
              type: string
              format: date-time
              description: Voucher expiry, when the provider returns one.
            voucher_status:
              type: string
              description: Provider reported voucher status (for example `active`).
          additionalProperties: false
    operation_error:
      type: object
      description: >-
        Provider mapped error attached to a failed operation or to a failed
        redemption aggregate.
      required:
        - error_code
        - message
      properties:
        error_code:
          type: string
          description: >-
            Provider namespaced error code (for example `1Voucher.2402`,
            `1Voucher.transport_error`).
          example: 1Voucher.2402
        message:
          type: string
          description: Human readable explanation supplied by the provider.
          example: The voucher you have entered could not be found
    problem_detail:
      type: object
      description: >
        RFC 9457 problem details. Returned with `Content-Type:
        application/problem+json` on every error response.
      required:
        - type
        - title
        - status
        - code
      properties:
        type:
          type: string
          format: uri
          description: A URI reference identifying the problem type.
          example: https://api.momentco.io/problems/resource_not_found
        title:
          type: string
          description: A short, human readable summary of the problem type.
          example: Resource Not Found
        status:
          type: integer
          description: The HTTP status code applicable to this problem.
          example: 404
        detail:
          type: string
          description: A human readable explanation specific to this occurrence.
          example: Redemption rdm_663a1b9c8e4f2a0012abcd34 not found
        instance:
          type: string
          description: A URI reference identifying the specific occurrence (request path).
          example: /collect/redemptions/rdm_663a1b9c8e4f2a0012abcd34
        code:
          type: string
          description: A machine readable code that describes the specific error condition.
          enum:
            - bad_request
            - unauthorized
            - missing_authorization
            - resource_not_found
            - resource_already_exists
            - conflict
            - invalid_state_transition
            - idempotency_conflict
            - operation_not_allowed
            - provider_error
            - service_unavailable
            - request_timeout
            - too_many_requests
            - internal_server_error
          example: resource_not_found
  examples:
    lookup_ott:
      summary: Lookup against OTT
      value:
        type: vouchers.ott
        source:
          pin: '9988776655443322'
          phone_number: '+27821234567'
    lookup_blu_token:
      summary: Lookup against Blu by token
      value:
        type: vouchers.blu
        source:
          token: 8276 8409 4119 1701
    lookup_blu_serial:
      summary: Lookup against Blu by serial number
      value:
        type: vouchers.blu
        source:
          serial_number: BL016C1E46AD2768
    lookup_ott_response:
      summary: OTT stored value lookup result
      value:
        type: vouchers.ott
        balance: 5000
        currency: ZAR
        source:
          pin: '9988776655443322'
          phone_number: '+27821234567'
        provider_metadata:
          pin_status: active
          denomination: 5000
    lookup_blu_token_response:
      summary: Blu stored value lookup by token
      value:
        type: vouchers.blu
        balance: 4000
        currency: ZAR
        source:
          token: 8276 8409 4119 1701
        provider_metadata:
          serial_number: BL016C1E46AD2768
          reference: '0902834592'
          expires_at: '2027-05-20T00:00:00Z'
          voucher_status: active
    lookup_blu_serial_response:
      summary: Blu stored value lookup by serial number
      value:
        type: vouchers.blu
        balance: 4000
        currency: ZAR
        source:
          serial_number: BL016C1E46AD2768
        provider_metadata:
          serial_number: BL016C1E46AD2768
          reference: '0902834592'
          expires_at: '2027-05-20T00:00:00Z'
          voucher_status: active
  responses:
    lookup_bad_request:
      description: Validation failed.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          example:
            type: https://api.momentco.io/problems/bad_request
            title: Bad Request
            status: 400
            detail: source is not valid for the selected type
            instance: /collect/redemptions/stored-value-lookups
            code: bad_request
    unauthorized:
      description: Authentication required.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          example:
            type: https://api.momentco.io/problems/unauthorized
            title: Unauthorized
            status: 401
            detail: The API key provided is invalid.
            instance: /collect/redemptions
            code: unauthorized
    operation_not_allowed:
      description: Provider does not support the requested operation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          example:
            type: https://api.momentco.io/problems/operation_not_allowed
            title: Operation Not Allowed
            status: 422
            detail: 1Voucher does not expose a stored value lookup operation
            instance: /stored_value/lookup
            code: operation_not_allowed
    internal_server_error:
      description: Unexpected server error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          example:
            type: https://api.momentco.io/problems/internal_server_error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred. Please try again later.
            instance: /collect/redemptions
            code: internal_server_error
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Authentication using Bearer tokens. Include your API key in the
        Authorization header.


        **Key Types:**

        - **Test Keys**: `sk_test_*` for development and testing

        - **Live Keys**: `sk_*` for production environments

        - **Public Keys**: `pk_test_*` or `pk_*` for client-side operations



        > 📩 **Need access?** [Contact Support](/documentation/support) to
        request your API keys.



        **Usage:**

        ```http

        Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc

        ```

````