openapi: 3.0.3
info:
  contact:
    email: support@marqeta.com
    name: Marqeta
  description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
  termsOfService: https://www.marqeta.com/api-terms
  title: Core accepted countries Program Balances API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- name: Program Balances
  description: Retrieve program funding balance data for financial reconciliation. Includes beginning and ending bank balances, amounts to send, and settlement details aggregated over configurable time periods.
paths:
  /views/programbalances/{time_agg}:
    get:
      operationId: getProgramBalances
      summary: Retrieve program funding balances
      description: 'Returns program funding balance data aggregated over the specified time period. Use this endpoint for financial reconciliation to retrieve beginning bank balance, amount to send, and ending bank balance. Supports daily, weekly, and monthly aggregation levels. An example request for daily balances: /views/programbalances/day?program=my_program&fields=beginning_bank_balance,amount_to_send,ending_bank_balance'
      tags:
      - Program Balances
      parameters:
      - $ref: '#/components/parameters/time_agg'
      - $ref: '#/components/parameters/program'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Program balance data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramBalancesResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted program balance data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/programbalancessettlement/{time_agg}:
    get:
      operationId: getProgramBalancesSettlement
      summary: Retrieve program settlement balances
      description: Returns program settlement balance data aggregated over the specified time period. Settlement balances reflect funds settled between Marqeta and the card networks. Use this alongside the programbalances view for full financial reconciliation.
      tags:
      - Program Balances
      parameters:
      - $ref: '#/components/parameters/time_agg'
      - $ref: '#/components/parameters/program'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Settlement balance data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementBalancesResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted settlement balance data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/activitybalances/{time_agg}:
    get:
      operationId: getActivityBalances
      summary: Retrieve activity balance data
      description: Returns cardholder activity balance data aggregated over the specified time period. Provides a summary of GPA balance changes driven by card transactions, loads, and transfers for program financial reporting.
      tags:
      - Program Balances
      parameters:
      - $ref: '#/components/parameters/time_agg'
      - $ref: '#/components/parameters/program'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Activity balance data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityBalancesResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted activity balance data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    offset:
      name: offset
      in: query
      description: Zero-based offset for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    fields:
      name: fields
      in: query
      description: Comma-delimited list of fields to include in the response. If not specified, all available fields are returned.
      schema:
        type: string
    format:
      name: format
      in: query
      description: Response format. Use 'json' for JSON responses or 'csv' for comma-separated bulk file format. Defaults to json.
      schema:
        type: string
        enum:
        - json
        - csv
        default: json
    time_agg:
      name: time_agg
      in: path
      required: true
      description: Aggregation time level for the data. Use 'day' for daily rollups, 'week' for weekly rollups, 'month' for monthly rollups, or 'detail' for individual record-level data.
      schema:
        type: string
        enum:
        - day
        - week
        - month
        - detail
    end_date:
      name: end_date
      in: query
      description: End date for filtering data (format YYYY-MM-DD). Returns records on or before this date.
      schema:
        type: string
        format: date
    start_date:
      name: start_date
      in: query
      description: Start date for filtering data (format YYYY-MM-DD). Returns records on or after this date.
      schema:
        type: string
        format: date
    limit:
      name: limit
      in: query
      description: Maximum number of records to return per request.
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
    program:
      name: program
      in: query
      required: true
      description: The name of your Marqeta card program. This parameter is required for most DiVA API endpoints to scope the data to your program.
      schema:
        type: string
  schemas:
    ProgramBalancesResponse:
      type: object
      description: Program funding balance data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of program balance records.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Date of the balance record.
              program:
                type: string
                description: Program identifier.
              beginning_bank_balance:
                type: number
                description: Opening bank balance for the period.
              ending_bank_balance:
                type: number
                description: Closing bank balance for the period.
              amount_to_send:
                type: number
                description: Net amount to send to or receive from the bank.
              currency_code:
                type: string
                description: ISO 4217 currency code for the balance figures.
    SettlementBalancesResponse:
      type: object
      description: Program settlement balance data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of settlement balance records.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Settlement date.
              program:
                type: string
                description: Program identifier.
              settlement_amount:
                type: number
                description: Total amount settled during this period.
              network:
                type: string
                description: Card network (e.g., VISA, MASTERCARD).
              currency_code:
                type: string
                description: ISO 4217 currency code.
    ActivityBalancesResponse:
      type: object
      description: Activity balance data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of activity balance records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Activity date or aggregation period.
              program:
                type: string
                description: Program identifier.
              beginning_balance:
                type: number
                description: Total GPA beginning balance for all cardholders.
              ending_balance:
                type: number
                description: Total GPA ending balance for all cardholders.
              load_amount:
                type: number
                description: Total funds loaded during the period.
              spend_amount:
                type: number
                description: Total funds spent during the period.
              currency_code:
                type: string
                description: ISO 4217 currency code.
    DivaResponseMeta:
      type: object
      description: Metadata included in DiVA API paginated responses.
      properties:
        total_count:
          type: integer
          description: Total number of records matching the query.
        limit:
          type: integer
          description: Maximum records returned per page.
        offset:
          type: integer
          description: Current page offset.
        has_more:
          type: boolean
          description: Whether additional pages of data are available.
    ErrorResponse:
      type: object
      description: Standard error response returned by the Marqeta DiVA API.
      properties:
        error_code:
          type: string
          description: Machine-readable error code.
        error_message:
          type: string
          description: Human-readable error description.
  responses:
    Unauthorized:
      description: Unauthorized. The provided application token and access token credentials are invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request. One or more required query parameters are missing or contain invalid values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    mqAppAndAccessToken:
      scheme: basic
      type: http