About Transactions

A transaction is an electronic message that carries information used for payment processing. Transactions usually originate when card holders attempt payments, either at a physical point of sale or online.

The Marqeta platform, as an issuer/processor, issues cards and processes transactions originated from these cards. A transaction on the Marqeta platform is represented by the transaction object.

At the end of the guide, you should understand:

  • The role transactions play in the payments ecosystem.
  • The use cases of transaction endpoints.
  • The transaction object on the Marqeta platform.
  • The transaction lifecycle.

Transactions in the payments ecosystem

In the payments ecosystem, transactions facilitate the following processes:

  • Authorization – The process of confirming whether a card is valid, business rules are met, and funds are sufficient, and then placing a temporary hold on those funds.
  • Clearing – The process of finalizing the hold on funds and posting the transaction on the card holder's account. This process is triggered by the merchant’s capture request.
  • Settlement – The process of transferring the funds between the merchant’s and the card holder’s banks. This process occurs simultaneously with the clearing.

Consequently, the most common transaction types are authorizations and clearings.

Transactions can be authorized, cleared, and settled either as dual-message transactions or as single-message transactions. The processing method may vary depending upon the payment method issuer, the type of card, or the region in which the transaction takes place.

  • In a single-message transaction, the merchant submits a single electronic message containing all data required for the authorization, clearing, and settlement of the transaction.
  • In a dual-message transaction, at the time of purchase, the merchant submits an electronic message containing the information required for an authorization decision. At a later point in time, the merchant submits a second message containing additional data required for clearing and settlement.

Most transactions processed by merchants are dual-message transactions. Single-message transactions usually occur when a card holder uses their PIN at a point of sale or at an ATM.

Besides authorizations and clearings, other common transaction types include:

  • PIN debit transactions – These transactions occur when a card holder attempts to make a payment using their PIN. Such a transaction typically contains all information required for authorization and clearing in a single electronic message.
  • Reversals – These transactions occur when a merchant cancels a transaction after the authorization has succeeded but before the clearing has taken place. Reversals may also be partial, so that only part of the initial authorization hold is released.
  • Refunds – These transactions occur when a card holder requests a merchant to return the funds for a transaction after the clearing has completed for it.
  • Chargebacks – These transactions occur when the issuer/processor disputes a completed transaction on behalf of the card holder.

Use cases of transaction endpoints

The Marqeta platform provides services for managing transactions on various granularity levels, from retrieving individual transactions that occurred within a limited time range to obtaining large aggregated transaction data sets. The following section describes common uses of transaction endpoints on the Marqeta platform.

Core API

You can use the Core API for performing operations on individual transactions. The use cases include investigation, reconciliation, and other operational needs. In particular, the Core API enables you to:

  • Retrieve a list of transactions associated with specific cards, campaigns, merchants, or account holders (users and businesses).
  • Retrieve information related to a specific transaction.
  • Retrieve the list of transactions related to a specific transaction.
  • Reverse an authorization for a specific transaction in a pending state.

If you are developing a financial mobile app, you might want to let your users view their transaction history in their profiles. In this case, you can call the /transactions endpoint and use the user_token query parameter to get transactions conducted by that user.

If you are building a customer support interface, you might want to provide the capability to review transactions and drill down to investigate what occurred with a given card. In this case, you can call the /transactions endpoint and use the card_token query parameter to get transactions for that specific card.

If you are creating an application for your accounting department, you might want to enable them to troubleshoot discrepancies and perform internal reconciliation. In this case, you can call the /transactions/{token}/related endpoint to list all transactions related to a specific transaction identified by the token path parameter.

For more information on the /transactions endpoint, see the Transactions page in the Core API reference.

DiVA API

You can use the Data insights, Visualization, and Analytics (DiVA) API for performing aggregate operations on transactions. The use cases include reporting, analytics, and data-driven decision making. In particular, the DiVA API enables you to:

  • Retrieve authorization transaction data aggregated over the specific time period, such as day, week, or month.
  • Retrieve settlement transaction data at a specific aggregation level, such as day, week, or month.
  • Retrieve chargeback data aggregated by transaction.
  • Retrieve funding load transaction data at a specific aggregation level.

If you are building a utility for a business intelligence system, you might want to provide the capability to analyze the daily settlement file and daily total authorizations, in order to calculate the transactions volume. In this case, you can call the /views/authorizations and /views/settlements endpoints.

For more information on the /views/authorizations and /views/settlements endpoints, see the Authorizations and Settlements pages in the DiVA API reference.

JIT Funding

Just-in-Time (JIT) Funding is a mechanism provided by the Marqeta platform that enables you to automatically fund accounts in real time during the transaction process.

In JIT Funding, transactions are made against card holder accounts that do not need to carry a balance. These transactions are usually dual-message transactions, where the first message is for loading funds and the second one is for spending them. You can monitor JIT-funded transactions as they occur and reconcile balances on card holder accounts.

For more information on JIT Funding, see the About Just-In-Time Funding page in the Developer Guides.

Webhooks

A webhook is a mechanism provided by the Core API that enables you to receive notifications about events as they occur in real time. The Marqeta platform sends such event notifications to a webhook endpoint hosted in your environment.

You can use the webhooks mechanism to receive notifications about transactions events, which include such information as transaction type, amount, how the transaction was funded, and so on.

For more information on how to create and configure webhooks, see the Webhooks Management page in the Core API reference.

Simulations

Transactions are originated from outside of your system, usually when a purchaser uses a card at a point of sale. Therefore, in your Marqeta production environment transaction objects are created as a result of messages coming from the card network, rather than by way of API calls to the Marqeta platform. For testing purposes, you can simulate creation of transaction objects in your Marqeta sandbox environment.

For more information on how to simulate creation of transactions, see the Simulating Transactions page in the Core API reference.


The transaction object

On the Marqeta platform, transactions are represented by the transaction object. The Marqeta platform creates a separate transaction object for each transaction message received from the card network. 

The attributes of a given transaction object depend on the transaction type. Some attributes are required for all transaction objects, such as:

  • type – Categorizes the transaction event. For the complete list of types, see the "Transaction events" section on the Event Types page.
  • state – The current state of the transaction. This is the only field that can change after the transaction object has been created. For more information, see "The transaction lifecycle" section.
  • amount – Amount of the transaction.

Each transaction is associated with an owner of the account that funds the transaction. The account owner can be a user, a business, or both. Consequently, each transaction object contains the user_token and/or the business_token attributes.

transaction object also contains one or more timestamp attributes that represent the transaction timeline, such as:

  • created_time – The date and time when the Marqeta platform created the transaction entry.
  • user_transaction_time – The date and time when the user initiated the transaction.
  • settlement_date – The date and time when funds were moved for a transaction.

If transaction objects are related, such as when they are part of the same dual-message transaction, the relationship is indicated in the preceding_related_transaction_token attribute.

transaction object may include embedded objects. For example, the gpa_order object describes how the transaction is funded. If the transaction is funded through Just-In-Time (JIT) Funding mechanism, gpa_order will contain the jit_funding object.

For the complete list of the transaction object's attributes, see the "Retrieve transaction" section on the Transactions page. 


The transaction lifecycle

The Marqeta platform creates transaction objects as a result of electronic messages received from the card network. From the moment of their creation, transaction objects are immutable, with the exception of the state attribute.

The way transactions transition through different states during their lifecycle depends on whether they are temporary or final transactions. Temporary and final transactions are closely related to single-message and dual-message transactions.

A dual-message transaction requires two or more transaction messages to complete, for example:

  • At the time of purchase, the merchant submits an electronic message containing the information required for an authorization decision.
  • At a later point in time, the merchant submits another electronic message containing additional data required for clearing and settlement.

In this scenario, the first message is a temporary transaction, which means it can be reversed. The last message is a final transaction.

Temporary transaction messages, such as authorizations, are handled synchronously, which means a transaction message flows in real time from the merchant to the issuer/processor (such as Marqeta) and then back to the merchant. Final transaction messages are handled asynchronously, because capture requests can be submitted at a later time.

Some transactions, such as PIN debit transactions, contain all the information required for authorization and clearing in a single electronic message. These are typically final transactions that are handled synchronously.

On the Marqeta platform, temporary transaction types, such as authorizations, always start in a PENDING state and move to either a CLEARED state or a DECLINED state. Final transaction types, such as clearings or reversals, start and remain in a COMPLETION state.

Temporary transactions transition from one state to another during their lifecycle, as a result of transaction events coming from the card network. The following diagram illustrates state transitions of an authorization transaction that was partially cleared and partially reversed. The diagram depicts transaction objects that were created on the Marqeta platform during this chain of events and indicates relationships between these objects, as follows:

  1. The card network sends an authorization message for $100 to the Marqeta platform. The Marqeta platform creates a transaction object A of type authorization in a PENDING state and puts a temporary hold on $100.
  2. The card network sends a clearing message for $40 to the Marqeta platform. The Marqeta platform creates a transaction object B of type clearing in a COMPLETION state (related to the object A), puts a final hold on $40, and updates the temporary hold to $60.
  3. The card network sends a clearing message for $20 to the Marqeta platform. The Marqeta platform creates a transaction object C of type clearing in a COMPLETION state (related to the objects A and B), puts a final hold on $20, and updates the temporary hold to $40.
  4. The card network sends a reversal message for $40 to the Marqeta platform. The Marqeta platform creates a transaction object D of type reversal in a COMPLETION state (related to the objects A, B, and C), releases the hold on $40, updates the temporary hold to $0, and transitions the transaction object A to a CLEARED state.