Exploring the DiVA API
The DiVA API provides several endpoints that enable you to monitor your business progress and perform other essential business operations. Once you have your DiVA API tokens, you can use a tool such as Postman to explore and test the DiVA endpoints.
Setting up a call in Postman
Copy section link
Testing a DiVA endpoint using Postman is easy. To set up a call to a DiVA endpoint:
-
Specify the endpoint you want to test. For example, to get the settlements for the current week, use the program short name in the following URL:
https://diva-api.marqeta.com/data/v2/views/settlements/day?program=my_program -
Select GET.
-
Set up authentication by selecting an authorization type in the Authorization area and entering your tokens. For more information, see Authentication.
-
Select Send. Your response appears in the output window.
Refining the response
Copy section link
You can customize your response by using query and field filters, sorting and pagination, aggregation, and grouping.
Aggregation
Copy section link
The example request in the previous section aggregates the result for the current day. Most DiVA requests can be also be viewed in a detailed format, or aggregated by week or month. For example, you can alter the request to get the response data aggregated for the current week as follows:
https://diva-api.marqeta.com/data/v2/views/settlements/week?program=my_program
For more details on aggregation levels, see Data Aggregation Levels.
Filters
Copy section link
You can filter your results using query filtering or field filtering. To filter the fields to include in the response, specify those fields in the request.
For example, if you append post_date, settlement_date, transaction_type and network to the GET request as shown below, only those fields are returned in the response:
https://diva-api.marqeta.com/data/v2/views/settlements/week?program=my_program&fields=post_date,settlement_date,transaction_type,network
This request generates a response similar to the following:
For more on filtering fields, see Field Filtering. For information on filtering using queries, see Query Filtering.
Automating jobs based on updates
Copy section link
Use the report_load_timestamp field in key endpoints to configure your automated jobs to trigger based on updates.
This timestamp is presented in UTC.
Other customizations
Copy section link
For more details and examples of customizing the response using sorting, pagination, aggregation, and grouping, see Response Customization.
Useful endpoints
Copy section link
Curious which endpoints may be useful for monitoring and reporting on operations? This section summarizes some reporting needs addressed by the DiVA endpoints.
Reconciling financial transactions
Copy section link
For reconciling financial transactions, the /programbalances and /programbalancessettlement endpoints provide useful information.
Ask your Marqeta Customer Service representative if you have questions about which data points are appropriate for your program.
Program balances
Copy section link
The /programbalances/day endpoint includes the beginning_bank_balance, amount_to_send, and ending_bank_balance fields, which are key indicators of program activity.
The following GET request returns relevant financial transaction information for the current day:
https://diva-api.marqeta.com/data/v2/views/programbalances/day?program=my_program&fields=beginning_bank_balance,amount_to_send,ending_bank_balance
The request generates a response similar to the following:
Program balances settlement
Copy section link
Using the /programbalancessettlements/day endpoint you can retrieve balance data based on settlements. Each row represents the balance data, including bank balance and the amount to transfer to fund your program.
For program balances settlement, the following GET request retrieves program balances settlement information for the current day:
https://diva-api.marqeta.com/data/v2/views/programbalances/day?program=my_program&fields=beginning_bank_balance,partner_funds_loads_net,deposit,ending_bank_balance
This request generates a response similar to the following:
Monitoring a funding account
Copy section link
To monitor a funding account, use the /programbalances/day endpoint. The /programbalances/day endpoint includes the beginning_bank_balance and ending_bank_balance fields, which show the change in program funds over the course of a day.
The following example shows a request that includes both bank balance fields:
https://diva-api.marqeta.com/data/v2/views/programbalances/day?program=my_program&fields=beginning_bank_balance,ending_bank_balance
This request generates a response similar to the following:
Monitoring program performance and growth
Copy section link
Several endpoints are useful for monitoring program performance and growth. Monitoring balances, authorizations, and settlements over time can provide data points for tracking progress.
Authorizations
Copy section link
The following request to the /authorizations endpoint returns the authorization amounts and count for the current month:
https://diva-api.marqeta.com/data/v2/views/authorizations/month?program=my_program&fields=acting_users,acting_cards,transaction_count,transaction_amount
This request generates a response similar to the following:
Settlements
Copy section link
For monitoring settlements, use the /settlements/detail endpoint. This endpoint includes the transaction_status and purchases fields, which provide useful settlement information.
The following example returns a detailed report that includes these fields:
https://diva-api.marqeta.com/data/v2/views/settlements/detail?program=my_program&fields=,transaction_status,post_date,purchases
This request generates a response similar to the following:
Clearings
Copy section link
To monitor clearings, use the /clearing/detail endpoint.
This endpoint includes the transaction_status, transaction_processing_type, and sig_purchases fields, which provide useful clearings information.
The /clearing/detail endpoint provides accounting-level line items that correspond to stages of the transaction lifecycle, making it ideal for reconciliation.
The following example returns a detailed report that includes these fields:
https://diva-api.marqeta.com/data/v2/views/clearing/detail?program=my_program&fields=transaction_status,post_date,sig_purchases
This request generates a response similar to the following:
Monitoring declined transactions
Copy section link
To monitor declined transactions, use the /declines endpoint with the Detail, Daily, Weekly, or Monthly aggregation level.
The /declines endpoint includes transaction_token, displaymessage, merchant, and transaction_amount fields, which provide information on declines.
The following example returns a detailed report that includes these fields:
https://diva-api.marqeta.com/data/v2/views/declines/detail?my_program&fields=transaction_token,displaymessage,merchant,transaction_amount
This request generates a response similar to the following:
Viewing chargeback details or status
Copy section link
To request the details of submitted chargebacks, use the /chargebacks endpoint. You can generate a status report using the /chargebacks/status endpoint, or chargeback details using /chargebacks/detail.
Chargeback status
Copy section link
To see the status of current chargebacks, use the /chargebacks/status endpoint. Useful fields include chargeback_token, chargeback_state, and provisional_credit_given.
This example requests those fields for chargebacks on the Mastercard network:
https://diva-api.marqeta.com/data/v2/views/chargebacks/status?program=my_program&network=MASTERCARD&fields=chargeback_token,chargeback_state,provisional_credit_given
This request generates a response similar to the following:
Chargeback detail
Copy section link
To see the details of current chargebacks, use the /chargebacks/detail endpoint.
This example requests the chargeback_token, chargeback_state, transaction_date, and transaction_type fields for current chargebacks:
https://diva-api.marqeta.com/data/v2/views/chargebacks/detail?program=my_program&fields=chargeback_token,chargeback_state,transaction_date,transaction_type
This request generates a response similar to the following:
Reviewing card and user demographics
Copy section link
The DiVA API provides endpoints for getting information on card and user demographics.
Cards
Copy section link
To get detailed card information, use the /cards/detail endpoint.
Fields of interest include user_token, uai, card_state, and active_card.
The following example requests those fields:
https://diva-api.marqeta.com/data/v2/views/cards/detail?program=my_program&fields=user_token,uai,card_state,active_card
This request generates a response similar to the following:
Users
Copy section link
To retrieve detailed user information, use the /users/detail endpoint.
Useful fields include user_token, uai, number_of_physical_cards, and number_of_virtual_cards.
This example retrieves those fields:
https://diva-api.marqeta.com/data/v2/views/users/detail?program=my_program&fields=user_token,uai,number_of_physical_cards,number_of_virtual_cards
The request generates a response similar to the following: