Marqeta.com
Support
/
5 minute read
November 25, 2020

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

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

You can customize your response by using query and field filters, sorting and pagination, aggregation, and grouping.

Aggregation

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

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:

Copied

Is this helpful?

Yes
No

For more on filtering fields, see Field Filtering. For information on filtering using queries, see Query Filtering.

Other customizations

For more details and examples of customizing the response using sorting, pagination, aggregation, and grouping, see Response Customization.

Useful endpoints

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

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

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:

Copied

Is this helpful?

Yes
No
Program balances settlement

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:

Copied

Is this helpful?

Yes
No
Monitoring a funding account

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:

Copied

Is this helpful?

Yes
No
Monitoring program performance and growth

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

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:

Copied

Is this helpful?

Yes
No
Settlements

For monitoring settlements, use the

/settlements
endpoint. This endpoint includes the
transaction_token
,
transaction_status
,
transaction_type
, 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/month?program=my_program&fields=&fields=transaction_token,transaction_status,transaction_type,purchases

This request generates a response similar to the following:

Copied

Is this helpful?

Yes
No
Monitoring declined transactions

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:

Copied

Is this helpful?

Yes
No
Viewing chargeback details or status

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

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:

Copied

Is this helpful?

Yes
No
Chargeback detail

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:

Copied

Is this helpful?

Yes
No
Reviewing card and user demographics

The DiVA API provides endpoints for getting information on card and user demographics.

Cards

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:

Copied

Is this helpful?

Yes
No
Users

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:

Copied

Is this helpful?

Yes
No

Feedback on this page?

If you feel we can do anything better, please let our team know.