Marqeta Program Balances API

openapi: 3.2.0
info:
  title: Marqeta DiVA Program Balances API
  description: The Marqeta DiVA (Data Insights, Visualization, and Analytics) API is a RESTful interface that provides programmatic access to production data from a Marqeta card program.
  version: '2'
  contact:
    name: Marqeta Support
    url: https://www.marqeta.com/company/contact
    email: support@marqeta.com
  termsOfService: https://www.marqeta.com/api-terms
servers:
- url: https://diva-api.marqeta.com/data/v2
  description: Production Server
security:
- basicAuth: []
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:
    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
    offset:
      name: offset
      in: query
      description: Zero-based offset for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    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
    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
    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
    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
    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
    limit:
      name: limit
      in: query
      description: Maximum number of records to return per request.
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
  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'
  schemas:
    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.
    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.
    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.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication. Use your application token as the username and your access token as the password. Contact your Marqeta representative to obtain DiVA API credentials.
externalDocs:
  description: Marqeta DiVA API Documentation
  url: https://www.marqeta.com/docs/diva-api/introduction