Skip to main content
A transaction begins when a cardholder attempts a payment at a physical or online point of sale. The act of swiping or tapping a card, or entering payment details online, initiates a series of electronic messages that contain information about this payment. Transaction processing occurs when the electronic messages about payments travel from the merchant’s point of sale to the issuer processor (e.g., Marqeta) via the payments ecosystem. Once these messages have been processed, funds move from the cardholder’s account to the merchant’s account. For more information, see the About Transactions guide. At the end of this guide, you should understand:
  • The transaction object and its properties
  • The information relayed in transaction responses
  • Marqeta’s rules for processing transactions
  • The different types of transactions
  • Common transaction processing flows

Transaction object

There are several properties within a transaction. The key properties to consider are:
  • type — Determines the type of transaction being requested. For example, ATM withdrawal.
  • preceding_related_transaction_token — References a preceding pending authorization or authorization advice.
  • amount — Indicates the transaction amount.
  • payment_channel — Indicates the type of authorization, which helps you distinguish point-of-sale transactions from e-commerce transactions. Possible values include ATM, ECOMMERCE, MAIL, MOTO, PHONE, OTHER.
JSON
{
  "type": "authorization",
  "state": "PENDING",
  "token": "string",
  "preceding_related_transaction_token": "string",
  "amount": "70.00",
  "gpa_order": {
    "jit_funding": {
      "token": "string",
      "method": "pgfs.authorization",
      "amount": "70.00",
      "original_jit_funding_token": "string"
    }
  },
  "transaction_metadata": {
    "payment_channel": "ECOMMERCE"
  }
}

Transaction currencies

The card networks send currency conversion data to the Marqeta platform when a transaction is not in a supported settlement currency, converting that transaction from the local currency into the billing currency of the cardholder. The details of transaction currencies are outlined below.
  • The network converts the local currency into the cardholder’s billing currency and shares this information with Marqeta.
    • amount and jit_funding.amount are shown in the cardholder’s billing currency.
  • Currency conversion details are shown in the currency_conversion object.
    • original_amount — Indicates the amount in the local transaction currency.
    • conversion_rate — Indicates the rate to convert between the local currency and the cardholder’s billing currency.
    • original_currency_code — Indicates the local currency code.
  • The network always provides currency conversion information.
    • A conversion rate of 1.000000 will be displayed for local transactions.
  • The settlement_data object provides settlement data for multi-currency programs.
    • amount — Indicates the amount that will be settled by the network.
    • conversion_rate — Indicates the rate between local and settlement currencies.
    • currency_code — Indicates the settlement currency code.
JSON
{
  "request_amount": 2.99,
  "amount": 2.99,
  "currency_conversion": {
    "network": {
        "original_amount": 2.99,
        "conversion_rate": 0.700000,
        "original_currency_code": "826"
    },
    "settlement_data": {
        "amount": 198.08,
        "conversion_rate": 1.0,
        "currency_code": "978"
    }
  },
  "currency_code": "USD"
}

Transaction responses

Transactions can be approved or declined for many reasons, such as account funding, card status, and so on. The following attributes are displayed in the response object on the transaction payload to give you more details about the approved or declined transaction:
  • code — Identifies the outcome of the transaction.
  • memo — Corresponds to the code and provides details on the transaction results.
  • additional_information — Provides further clarification of the response, such as:
    • If the online or offline PIN try limit was exceeded.
    • If the velocity control threshold was exceeded.
JSON
{
  "response": {
    "code": "1872",
    "memo": "Pin try limit exceeded",
    "additional_information": "Offline pin try limit exceeded"
  }
}
JSON
{
  "response": {
    "code": "1806",
    "memo": "Card not active"
  }
}
JSON
{
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  }
}

Marqeta processing rules

Marqeta performs several checks during a transaction to ensure that it is valid and that the card and cardholder are legitimate. These checks are performed before any funding request is made. Marqeta checks commonly include, but are not limited to:

Card and cardholder security checks

Card and cardholder security checks are completed during a transaction, prior to requesting Gateway Just-in-Time (JIT) Funding. These checks ensure that the cardholder and the card are in the correct state that allows them to perform a transaction. The JIT Funding gateway is only called after these checks are successfully passed. If a card or cardholder fails any of these checks, you will see one or more of the following response codes:
Response CodeDescription
1001Card expired.
1003Card suspended.
1004Card stolen — pickup.
1005Card lost.
1011Card not found.
1014Account not found. The account was not created for the currency in the transaction.
1806Card not active.
1809Incorrect PIN. (For online PIN only)
1813Cardholder not active. Transaction occurs outside the card start and end dates.
1825Invalid CID. Card security code is invalid; CVV does not match.
1872Offline PIN try limit exceeded.
1874Card suspicious — Expiration mismatch.
For a full list of response codes, see Transaction response codes.

Transaction control checks

Transaction control checks confirm that the values in the transaction do not exceed a given threshold, or that the transaction is not restricted in some way. For example, transactions in a contravened country or exceeding your specified spend controls are declined. If a card or cardholder fails one or more of these checks, you will see one or more of these response codes: Certain response codes in the following table are labeled as “optional functionalities.” You will receive response codes for optional functionalities only for those functionalities that have been enabled in your program’s application.
Response CodeDescriptionOptional Functionality?
1017Previously reversed.No
1826AVS decline. The address information submitted for the transaction failed AVS verification.Yes
1832Auth restriction found for given MID or MCC. Authorization control rules impose a restriction for this merchant ID or merchant category code.Yes
1834Transaction amount limit reached. It exceeds the weekly or monthly velocity control set for the program.Yes
1841Exceeds max auth amount limit. The transaction amount exceeds the velocity control set for the transaction.Yes
1864Transactions not allowed from this country. International transaction blocked due to the country or currency.No
1891Strong Customer Authentication — SCA contactless cumulative amount exceeded.No
1892Strong Customer Authentication — SCA contactless transaction count limit exceeded.No
1893Strong Customer Authentication — SCA contactless transaction limit exceeded.No
1897SCA LVP cumulative amount exceeded.No
1898SCA LVP transaction count limit exceeded.No
1899SCA LVP transaction limit exceededNo
For a full list of response codes, see Transaction response codes.

Digital wallet token checks

Digital wallet token checks pertain to both the creation of digital wallet tokens within the Marqeta system and the attempts to use a digital wallet token during a transaction. These checks ensure that the digital wallet tokens are in the correct state before funding the transaction. They also apply when Marqeta has requested step-up authentication, or has declined a token provisioning attempt. If a card or cardholder fails one or more of these checks, you will see one or more of the response codes listed below. Certain response codes in the following table are labeled as “optional functionalities.” You will receive response codes for optional functionalities only for those functionalities that have been enabled in your program’s application.
Response CodeDescriptionOptional Functionality?
1855Digital wallet token not found.Yes
1856Digital wallet token not active.Yes
1857Digital wallet token expired.Yes
1858Digital wallet token suspended.Yes
1863Additional identity verification required. (Verification required for yellow flow.)No
1882CVV attempt limit exceeded.No
For a full list of response codes, see Transaction response codes.

Transaction types

European countries use a dual-message service, which refers to transactions that process the clearing and settlement hours or days after the authorization. The single-message format is used in the US, and it uses one message for both functions. For European issuers, transactions in the US that use single-message are converted to dual-message. Issuers in Europe should not expect to receive pindebit transactions. Transaction types are split into two main categories:
1
Actionable events, which require an approval or action from you.
2
Informative events, which are notifications of ledger impact that do not require your action or approval.
See the following table for more information about actionable and informative events. See also Transaction event types.
Event NameCategoryRequired?
authorizationActionableYes
authorization.adviceInformativeYes
authorization.atm.withdrawalActionableNo
authorization.cashbackActionableNo
authorization.clearingInformativeYes
authorization.clearing.atm.withdrawalInformativeNo
authorization.clearing.representmentInformativeYes
authorization.incrementalActionableYes
authorization.quasi.cashActionableNo
authorization.reversalInformativeYes
authorization.reversal.issuerexpirationInformativeYes
balanceinquiryActionableNo
original.credit.authorizationActionableYes
original.credit.authorization.clearingInformativeYes
original.credit.authorization.reversalInformativeYes
refundInformativeYes
refund.authorizationActionableYes
refund.authorization.clearingInformativeYes
authorization.clearing.quasi.cashInformativeNo
refund.authorization.reversalInformativeYes

Linking transaction events

A token is a unique alphanumeric string that pertains to a single transaction event. Including various token fields in a transaction payload identifies specific aspects of an individual transaction. You can use the tokens in these fields to link separate transaction events. For examples of linked transaction events, see Transaction flows. The preceding_related_transaction_token maps back to a previous, related transaction, which may or may not be the original transaction. However, you can use the following variations of the preceding_related_transaction_token field to create a chain of tokens that will link back to the original authorization. See the definitions and the code sample below.
Note
Use the tokens in the following table for JIT Funding only.
Token NameDescription
gpa_order.jit_funding.tokenA unique token that refers to a JIT Funding approval request.
gpa_order.jit_funding.original_jit_funding_tokenA unique token that references the original JIT Funding request. This field is not present in the first authorization, but it is available in subsequent requests. You would use this for transactions that need more than one JIT Funding request, such as an incremental authorization.
incremental_authorization_jit_funding_tokensContains an array of JIT Funding tokens for incremental authorizations.
incremental_authorization_transaction_tokensContains an array of transaction tokens for incremental authorizations.
Note
Use the following tokens only for prefunded transactions or when using Commando Mode for your JIT gateway.
Token NameDescription
gpa_order.tokenA unique token for a gpa_order, requesting that funds be loaded onto a card.
incremental_authorization_transaction_tokensContains an array of transaction tokens for incremental authorizations.
JSON
{
  "transactions": [
    {
      "token": "8ea446a5-6051-465f-b392-fe7f248a6e23",
      "preceding_related_transaction_token": "2d7f3551-8d8d-4ce4-b561-15dfe934f8b3",
      "gpa_order": {
        "jit_funding": {
          "token": "ef025de1-996b-4d40-9670-eb777561aec6",
          "original_jit_funding_token": "35e7c623-b2fc-46b5-bdb8-a5b06597daf0",
          "incremental_authorization_jit_funding_tokens": [
            "32fadcd9-fb43-4cfd-820b-12fd6df82298"
          ]
        }
      },
      "incremental_authorization_transaction_tokens": [
        "6a148794-dfd8-4cd6-b04c-4aa5695f27e0"
      ]
    }
  ]
}

Transaction flows

Transactions follow common flows. These are largely based on merchant behavior, so the transactions shown here are a non-exhaustive set. Marqeta must process all clearings. Your system must be sufficiently flexible to accept clearings that do not conform to these flows. For more information on concepts relevant to payment card systems, as well as concepts specific to the Marqeta platform, see Payment Cards Concepts.

Successful transaction flows

The following flow diagrams illustrate examples of transactions occurring as expected and without error.

Authorization and clearing

Normally, merchants submit authorization events to place a hold on a certain amount of funds in the cardholder’s account. Merchants submit clearings to capture the final funds in the same amount as the authorization. Clearings can be higher if they include tips or fees, or they can be lower than the original authorization hold. You must account for this when developing your system. Merchants can also submit multiple clearances for an individual authorization event, which can occur if individual items from a single order ship one at a time.
Authorization and clearing

Clearing only

In some cases, you will receive a clearing without a linked authorization. In these cases, the clearings would not contain a preceding_related_transaction_token field. See below for some scenarios in which this might happen. Examples of “clearing only” transactions are:
  • Offline transactions are made without network connectivity, such as in an airplane, toll road, or car park.
  • Force posts that happen when Marqeta does not have sufficient criteria to match an authorization to a clearing, in which case, Marqeta is mandated to force post the transaction without a matching authorization.
  • A force capture, in which the merchant clears a transaction without any preceding authorization.

Authorization and reversal

If merchants want to undo an authorization hold that they have placed on a cardholder’s account, they must submit a reversal. Submitting a reversal means that the authorization hold has been either reduced or released. Reversals often occur when a transaction is canceled or a particular item is out of stock, and therefore the hold is released for the amount of that item.
Authorization and reversal

Authorization and partial clearing with reversal

A merchant can also capture a partial amount of funds and release the rest back to the cardholder. Merchants can perform these actions in any order, but the authorization must still be in a PENDING state.
Authorization and partial clearing with reversal

Authorization and incremental with clearing

This event flow allows merchants to increase the amount of funds in a pre-existing authorization hold, and it typically occurs when a cardholder adds a tip or extends a reservation, such as a hotel or car rental. An incremental authorization only increases the amount of an authorization hold when the clearing event is submitted, and it is linked to the original authorization. The clearing amount will reflect the combined amount of authorization plus any incremental amounts.
Authorization and incremental with clearing

Authorization and advice with clearing

This flow occurs when a merchant needs to reduce an existing authorization hold for a transaction. Advice events use the same method as reversals, and are also supported wherever reversals are supported. An advice event replaces the existing authorization with a lower amount. These events typically occur when using automated fuel dispensers, where the actual amount is not known at authorization time, but the authorization is updated as soon as the fuel has been dispensed. Marqeta’s system processes the transaction, but only sends information about the amount that must be released, using the same method as a reversal.
Authorization and advice with clearing

Authorization and multiple incrementals with clearing

This flow depicts the same flow as Authorization and incremental with clearing, in which the merchant increases the amount of an existing authorization hold. However, in this situation, the authorization hold has been increased twice. Usually there is only one event, but there is no limit to the number of events that are possible in this situation. In this type of event, all incrementals link back to the original authorization and the clearing event contains the combined amount of the authorization hold and all incremental amounts. Marqeta populates the incremental_authorization_transaction_tokens field within the clearing event to show the original authorization and the incrementals linked to it.
Authorization and multiple incrementals with clearing

Authorization and partial clearing with expiration

If a merchant partially captures an authorization hold, then the remainder of the authorization hold will stay on the cardholder’s account. Merchants should immediately reverse the authorization hold. However, if a merchant does not reverse the charge, Marqeta’s authorization expiration job releases the pending authorization hold on the cardholder’s account after a certain amount of time.
Note
Typically, the time frame for releasing pending authorizations is nine days from the time of authorization. The time frame is defined by Marqeta and depends on your system’s configuration.
When the authorization time expires, Marqeta sends an issuer expiration reversal event, allowing for the release of held funds from the cardholder account. This type of event does not guarantee that the merchant will not send clearing events afterwards, but it does indicate that the merchant is not likely to capture those funds. For more information on how to handle a similar scenario, see Authorization and expiration with clearing.
Authorization and partial clearing with expiration

Authorization and clearing with refund

In this flow, the cardholder has completed a transaction that has fully cleared, but the cardholder is requesting a refund. This can happen when, for example, a cardholder returns goods to a merchant. Merchants must send a refund event, which is a unique event that credits a cardholder account, and does not need to be linked back to an authorization event. The Marqeta system displays separate events for the initial authorization and the clearing events.
Authorization and clearing with refund

Authorization and clearing with partial refund

Similar to the flow described in Authorization and clearing with refund, merchants can also send a partial refund so that only a partial amount of the funds captured in the original authorization can be refunded. This can happen if, for example, the cardholder returns one of many items purchased in a single transaction.
Authorization and clearing with partial refund

Authorization attempt and STIP decline

If the Marqeta platform is not available to handle authorizations, the card networks intervene using a process known as Stand-in Processing (STIP). A STIP decline happens when there is an attempt to authorize a transaction but it cannot be processed. At that time, the card network steps in and makes the final decision about the authorization. A STIP decline can occur for many reasons. The field standin_reason can provide details as to why the STIP decline happened. In this example flow, Marqeta did not see or process the original authorization and did not respond to the event. Therefore, no funds were held and an informative STIP event was provided. For more details, see Network Stand-in Processing decline. As card networks do not have access to cardholder balances, you would typically configure your application to use STIP to decline authorizations in such a scenario. However, you can set up your configuration to approve certain amounts, if you wish.
Authorization attempt and STIP decline

Failed authorization and STIP decline with reversal

If Marqeta returns a response to the card network that is later declined, the card network sends Marqeta two events: the original STIP message and a standard reversal event. This can happen, for example, if a timeout occurs or if there is an issue with the acquirer. See Authorization attempt and STIP decline for further details. This method ensures that any held funds are released from the cardholder account, as the authorization has been declined. For more details, see Network Stand-in Processing decline.
Failed authorization and STIP decline with reversal

Possible transaction errors

The following flow diagrams illustrate examples of transactions with errors or unexpected behaviors.

Authorization and unlinked clearing (duplicate charging) with expiration

In this flow, the merchant submits a clearing for an authorization that was completed, but the clearing did not link to the authorization. This scenario causes “double charging,” where an authorization hold has already been placed on the cardholder account from the original authorization, but there is an additional hold placed on the cardholder account for the final amount from the clearing event. This might happen when fields provided by the merchant differ from that of the authorization. Marqeta’s issuer expiration event can remediate this situation by releasing the authorization hold from the original authorization back to the cardholder so that those funds become available again.
Authorization and unlinked clearing (duplicate charging) with expiration

Authorization and expiration with clearing

In this flow, the authorization has expired and the held funds have been released, but a clearing event has been submitted after the expiration. The time frame of an expiration is predefined; however, it does not stop merchants from submitting clearings after an initial authorization has expired. As a result, a clearing can be “force posted” and, if possible, Marqeta will attempt to link the clearing event to the original authorization within 21 days of that authorization.
Authorization and expiration with clearing

Authorization and clearing for higher amount

Sometimes merchants submit clearings that are higher than the original authorization amount. This typically happens when processing additional tips or fees, and it can lead to negative cardholder balances. You should consider how you would like to handle these situations, as clearings are informative events that must be processed and applied to the cardholder’s account.
Authorization and clearing for higher amount

Clearing matched to authorization instead of advice

Merchants sometimes provide differences in data elements when clearing transactions, which can cause problems when linking clearings to the appropriate advice message. If Marqeta cannot link a clearing to the advice, then Marqeta can link the clearing to the original authorization. Marqeta is continually improving matching logic to reduce the possibility of such an occurrence.
Clearing matched to authorization instead of advice

Refund authorization and unlinked refund clearing (duplicate charging) with expiration

Merchants can send refund events that are authorized prior to sending the refund, which are known as online refunds. Merchants can then confirm whether the card is still active before sending the refund. Unlike other events, cardholder funds must not be adjusted until the clearing event has been received. Marqeta will attempt to link the refund clearing to the refund authorization whenever possible. If Marqeta cannot link the refund clearing to the refund authorization, then the standard issuer expiration and refund events are used to link them.
Refund authorization and unlinked refund clearing (duplicate charging) with expiration

Network Stand-in Processing decline

Stand-in Processing (STIP) occurs when one party in the authorization flow is unable to complete processing within the time allocated or when specific transactional rules are set up at the network level. In such cases, card issuers can let the card network approve transactions on their behalf. When a transaction is processed using STIP, the Marqeta platform sends an informative event webhook that has no impact on the cardholder balance. The standin_reason provides a reason for the STIP decline. Common reasons include, but are not limited to:
  • issuer_timeout
  • issuer_unavailable
  • acquirer_issue
  • suspected_fraud_transaction
There are two types of processes in which STIP can occur:
  • Authorizations that the Marqeta platform did not receive.
  • Authorizations that the Marqeta platform received and processed.
JSON
{
  "transactions": [
    {
      "type": "authorization",
      "state": "DECLINED",
      "identifier": "12544010",
      "token": "TRANSACTION A",
      "amount": 3.50,
      "response": {
        "code": "1844",
        "memo": "Network decline advice"
      }
      "standin_by": "NETWORK",
      "standin_reason": "acquirer_issue"
    }
  ]
}

Commando Mode transactions

Marqeta Commando Mode can be configured to be enabled manually or invoked automatically after specific criteria has been met. Marqeta provides three seconds for funding requests to be approved before stepping in to approve on your behalf (if configured to do so). Any event approved during Commando Mode will contain a different funding source, which does not contain the jit_funding method. In this event, the type field can be used to determine the funding event and the cardholder impact for that transaction. The preceding_related_transaction_token will link to the previous authorization, which was approved via COMMANDO_AUTO or COMMANDO_MANUAL. For more information, see Commando Mode.
JSON
{
  "token": "47ec5a14-2d82-4f04-b13f-edf442191679",
  "type": "authorization",
  "state": "PENDING",
  "duration": 4104,
  "amount": 11.56,
  "gpa_order": {
    "jit_funding": {
      "token": "7c91019b-27a4-4c00-bedc-8cd8f55d7c59",
      "method": "pgfs.authorization",
      "user_token": "f3984c1f-c920-42e4-982a-dfa0bd7820a1",
      "acting_user_token": "f3984c1f-c920-42e4-982a-dfa0bd7820a1",
      "amount": 11.56
    }
  },
  "standin_approved_by": "COMMANDO_AUTO",
  "standin_by": "COMMANDO_AUTO"
}
JSON
{
  "type": "authorization.clearing",
  "state": "COMPLETION",
  "amount": 11.54,
  "preceding_related_transaction_token": "47ec5a14-2d82-4f04-b13f-edf442191679",
  "gpa_order": {
    "funding": {
      "amount": 11.54,
      "source": {
        "type": "program",
        "token": "**********urce",
        "active": true,
        "name": "Commando Mode"
      }
    }
  }
}

Card acceptor object

The card acceptor object displays specific details on where the card is being used. This contains information about the card acceptor, such as the merchant identifier (MID), merchant category code (MCC), or MCC group.
  • mid — The merchant identifier used to identify the merchant. This can be used to block specific merchants from transacting.
  • mcc — The merchant category code used for categorizing merchants. For example, code 7321 refers to rental cars.
  • name — The merchant name. This can vary between authorization and clearing.
  • city — The merchant city.
JSON
{
  "card_acceptor": {
    "mid": "112137000108778",
    "mcc": "5815",
    "network_mid": "112137000108778",
    "name": "APPLE.COM/BILL",
    "city": "866-712-7753",
    "state": "06",
    "zip": "95014",
    "country": "USA"
  }
}

Point of sale object

The point of sale (pos) object will provide key details on how the card was used. It indicates the type of terminal, what input capability the terminal has, and how the card was presented.
  • pan_entry_mode — Details how the card was presented to the terminal. Values consist of, but are not limited to:
    • CHIP — The card was inserted into the chip reader of the terminal.
    • CHIP_CONTACTLESS — The card was tapped contactlessly on the terminal.
    • MANUAL — The PAN was manually entered. This is common for e-commerce.
  • card_presence / card_holder_presence — The card and cardholder were present. This is true for most point-of-sale transactions and false for e-commerce transactions.
  • partial_approval_capable — The merchant allows for part of the funds to be approved. The true amount approved can be lower than the requested amount.
  • pin_present — The PIN was entered and passed to the Marqeta platform for validation. This is true when the online PIN is used and passed to the Marqeta platform. This is false for offline PIN transactions.
  • card_data_input_capability — The terminal capability, including if the terminal can support CHIP. Values include CHIP, CHIP_CONTACTLESS, KEY_ENTRY, and MAG_STRIPE.
JSON
{
  "pos": {
    "pan_entry_mode": "CHIP_CONTACTLESS",
    "pin_entry_mode": "TRUE",
    "terminal_id": "TR100000",
    "terminal_attendance": "ATTENDED",
    "card_holder_presence": true,
    "card_presence": true,
    "card_data_input_capability": "CHIP_CONTACTLESS",
    "partial_approval_capable": false,
    "pin_present": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Fraud object

The fraud object displays risk parameters and the likelihood that a transaction is or is not fraudulent. On the network side:
  • transaction_risk_score — The transaction fraud risk score calculated by the card network; a higher score indicates a higher risk. Values include 1-99.
On the issuer-processor side:
  • rule_violations — Rules flagged at transaction times. Values include [String].
  • recommended_action — Transaction-specific suggestions based on the rules defined for the program. When a rule is triggered, the value is DECLINE. Values include APPROVE, DECLINE, and NOT_PERFORMED.
For more information, see RiskControl Objects.
JSON
{
  "fraud": {
    "network": {
      "transaction_risk_score": 27
    },
    "issuer_processor": {
      "recommended_action": "APPROVE",
      "rule_violations": [
        "24hr.velocity.exceeded"
      ]
    }
  }
}

Transaction processing responsibilities

If you offer a Marqeta card program in Europe, there are several responsibilities that you and Marqeta maintain. These responsibilities include:
ResponsibilityPowered ByManaged By
Process informative webhook events, such as clearings and reversalsYouYou
Validate transactionsMarqetaMarqeta
Limit transactional spending according to the velocity controls you specifyMarqetaMarqeta
Process transactions and provide you with transaction webhooksMarqetaMarqeta