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