About Reporting

The Marqeta platform supports several mechanisms to retrieve data for use in reports. As a Marqeta customer, you can use the Program Dashboard to generate reports based on several common models. As a developer, you can retrieve custom data sets from Marqeta APIs. You can then use the data with your in-house reporting engine.

At the end of this guide, you should understand:

  • How to access reports through the Program Dashboard.
  • When to use the DiVA API to retrieve data for reports.
  • When to use the Core API to retrieve data for reports.

Program Dashboard

The Program Dashboard application provides a suite of tools for performing user and transaction administration tasks. You can display a list of available reports by clicking the Reports link in the Program Dashboard sidebar. These reports include categories such as card holder balance, settlement amount, and load summary. 


DiVA API

Use the Data insights, Visualization, and Analytics (DiVA) API to retrieve large (multi-page) data sets such as transaction or balance data. For example, you can use a DiVA query to retrieve all transactions during one day for reconciliation purposes.

The DiVA API includes options for retrieving and aggregating data. You can specify responses in JSON, CSV, or XLXS format. In addition, you can define multiple filters within the query string for any column returned in the data schema. For example, you can create a filter that returns settlement information for a subset of card holders for multiple dates. For more information on filter syntax and other response options, see Response Customization.

For more information about available endpoints, see the DiVA API Reference.


Core API

Use the Core API to retrieve specific types of data within a limited time range. For example, you can use the /transactions API endpoint to retrieve transactions for a specific user, business, card, transaction type, transaction state, merchant, and campaign. In addition, you can define multiple filters within the query string for any column returned in the data schema.

You should use a Core API endpoint when you intend to pass a parameter in your query. For optimal system performance, use this endpoint for queries that return a single-page response, and that return data for the last six months. 

Note: Marqeta may limit the amount of transaction history available through the Core API. To access additional historic data, use the DiVA API.

For more information about available endpoints, see the Core API Reference.

Webhook event notifications

After you set up a webhook endpoint, Marqeta can send push notifications for events such as transactions and state transitions. Generated asynchronously, these notifications enable you to track events in real-time and store their data locally. 

To enable webhooks, you must first set up an environment to listen for and process event notifications. You can then use a single webhook endpoint to receive all event notifications, or define separate webhooks for organizing notifications by event type. 

For more information, see the Webhooks Reference


Analyzing card usage

You can use a combination of fields in the transactions object to understand detailed information about how a transaction was processed:

  • pos.cardholder_presence – indicates whether the card holder was present for the transaction.
  • pos.card_presence – indicates whether the card was present for the transaction.
  • pos.pin_entry_mode – indicates whether a PIN was used in the transaction.
  • pos.processing_type (possible values: MAGSTRIPE, CHIP, CHIP_FALLBACK, UNKNOWN) – indicates how the instrument was used. Chip fallback occurs when a chip-capable terminal is malfunctioning and the magnetic stripe is used to perform the transaction. For tokenized payments, the processing type is MAGSTRIPE. Unknown includes everything else.
  • transaction_metadata.payment_channel (possible values: ATM, ECOMMERCE, OTHER) – indicates where the transaction occurred — at an ATM, internet merchant (ECOMMERCE), or somewhere else, such as a physical POS (OTHER).

For example, you can distinguish between different types of physical card transactions. The processing type is MAGSTRIPE, if it was swiped with a magnetic stripe, and CHIP if it was dipped with a chip. In both cases, the card is present and the channel is OTHER. You can also identify key-entered transactions by looking for transactions where the card is present, the channel is OTHER, and the processing type is UNKNOWN.

You can find potential issues with transactions by looking for unexpected combinations — for example, a processing type of CHIP and channel of ECOMMERCE.