About Transactions
A transaction is an electronic message that carries information used for payment processing. Transactions usually originate when cardholders 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 this 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 response codes that describe transaction outcomes.
-
The transaction lifecycle.
Transactions in the payments ecosystem
Copy section link
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 cardholder’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 cardholder’s banks.
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 cardholder 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 cardholder 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 cardholder 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 cardholder.
Use cases of transaction endpoints
Copy section link
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 datasets. The following section describes common uses of transaction endpoints on the Marqeta platform.
Core API
Copy section link
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.
Webhooks
Copy section link
Webhooks enable you to receive notifications about events as they occur in real time. The Marqeta platform sends event notifications to a webhook endpoint hosted in your environment.
You can use webhooks to receive notifications about transactions events, which include such information as the transaction type, amount, and how the transaction was funded.
For information on how to create and configure webhooks, see the Webhooks API reference page. See the transaction events for which you can set webhooks in the Event Types API reference page.
DiVA API
Copy section link
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
Copy section link
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 cardholder 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 cardholder accounts.
For more information on JIT Funding, see the About Just-in-Time Funding page in the guides collection.
Simulations
Copy section link
Transactions originate 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 through API calls to the Marqeta platform.
For testing purposes, you can simulate the creation of transaction objects in your public or private sandbox environment.
For more information on how to simulate the creation of transactions, see the Simulating Transactions page in the Core API reference.
The transaction object
Copy section link
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 of the Event Types API reference 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.
Dual-message transactions retain the original token in subsequent transaction messages even if the card used changes owners.
A 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.
A 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 API reference page.
Transaction response codes
Copy section link
You can use the response.code field to help understand the transaction.
In general, the type field categorizes the attempted transaction type, and the response.code field describes the outcome of that attempt.
For example:
-
A combination of
type = authorizationandresponse.code = 1001indicates a card authorization attempt that failed because the card was expired. -
A combination of
type = authorizationortype = pindebitwith aresponse.codeof 0000, 0002, or 1830 indicates a successful transaction. All other response codes indicate failed transactions.
The following response codes table describes the possible values for the response.code field.
For more information about the type field, see the Transaction events section on the Event Types API reference page.
Response codes table
Copy section link
| Code | Description |
|---|---|
0000 |
Transaction approved or completed successfully. |
0002 |
Partially approved. |
1001 |
Card expired. |
1002 |
Card suspicious. |
1003 |
Card suspended. |
1004 |
Card stolen — pickup. |
1005 |
Card lost. |
1011 |
Card not found. |
1012 |
Cardholder not found. It is possible that the card is valid, but cardholder has not yet been created. |
1014 |
Account not found. The account was not created for the currency in the transaction. |
1015 |
Invalid request. Request cannot be parsed, or relevant data not found. |
1016 |
Not sufficient funds. Funds in account are less than the auth amount. |
1017 |
Previously reversed. |
1018 |
Previously completed. |
1019 |
Further activity prevents reversal. |
1020 |
Further activity prevents void. |
1021 |
Original transaction has been voided. |
1022 |
No savings account. |
1023 |
No checking account. |
1802 |
Missing fields. |
1803 |
Extra fields exist. |
1804 |
Invalid card number. PAN information is missing from the request. |
1806 |
Card not active. |
1808 |
Card not configured. |
1809 |
Incorrect PIN. |
1810 |
Invalid amount. Amount field is null or less than zero. |
1811 |
System error related to the database. This error is sent to the network. |
1812 |
System error related to business logic. For example, the original transaction might not be found. |
1813 |
Cardholder not active. Transaction occurs outside the card start and end dates. |
1814 |
Cardholder not configured. Start and end dates have not been configured. |
1815 |
Cardholder expired. Transaction date occurs after the cardholder’s end date. |
1816 |
Original not found, and no pre-auth exists. |
1817 |
Usage limit reached. |
1818 |
Configuration error. |
1819 |
Invalid terminal. |
1820 |
Inactive terminal. |
1821 |
Invalid merchant. |
1822 |
Duplicate entity. |
1823 |
Invalid acquirer. |
1824 |
Accounting exception. |
1825 |
Invalid CID. Card security code is invalid; CVV does not match. |
1826 |
AVS decline. The address information submitted for the transaction failed AVS verification. |
1827 |
AVS no info. |
1828 |
Card is active. |
1829 |
AVS match. |
1830 |
Card account verification success. |
1831 |
Card not present. |
1832 |
Auth restriction found for given MID or MCC. Authorization control rules impose a restriction for this merchant ID or merchant category code. |
1833 |
Cryptographic failure. The card was presented, and the chip failed a verification test because of an invalid cryptogram or ARPC verification failed HSM check. |
1834 |
Transaction amount limit reached. It exceeds the weekly or monthly velocity control set for the program. |
1835 |
Card product controls prevent transaction. |
1836 |
JIT clearing failure. |
1837 |
JIT refund failure. |
1838 |
International transaction decline. |
1839 |
JIT reversal failure. |
1840 |
Real-time fee group not found. |
1841 |
Exceeds max auth amount limit. The transaction amount exceeds the velocity control set for the transaction. |
1842 |
Account load failed. |
1843 |
Network loads not allowed. |
1844 |
Issuer timeout advice. The card network has advised of a decline. |
1845 |
Transactions other than ATM and e-commerce not allowed. |
1846 |
ATM transactions not allowed. |
1847 |
E-commerce transactions not allowed. |
1848 |
Mail order transactions not allowed. |
1849 |
Phone order transactions not allowed. |
1850 |
Card not present. |
1851 |
Cardholder not present. |
1852 |
PIN not present. |
1853 |
ICC not present. |
1854 |
Card security code not present. |
1855 |
Digital wallet token not found. |
1856 |
Digital wallet token not active. |
1857 |
Digital wallet token expired. |
1858 |
Digital wallet token suspended. |
1859 |
Digital wallet token not present. |
1860 |
Digital wallet token suspicious. |
1861 |
Transaction account management limit reached. |
1862 |
Token activation request card product config decline. |
1863 |
Additional identity verification required. |
1864 |
Transactions not allowed from this country. International transaction blocked due to the country or currency. |
1865 |
Insufficient funds in program reserve account. |
1866 |
Invalid card service code. |
1868 |
Quasi Cash txn not allowed (processing code 11). |
1869 |
KYC is required. |
1870 |
Reloads are disabled for entity. |
1871 |
Push-to-Card disbursement error. |
1872 |
Offline PIN try limit exceeded. |
1873 |
Chip fallback not allowed. |
1874 |
Card suspicious — Expiration mismatch. |
1875 |
Partial JIT not allowed. |
1876 |
Account funding transactions are unsupported. |
1877 |
Real-Time Decisioning decline. |
1878 |
Corresponding JIT load failure. |
1879 |
Credit voucher not allowed. |
1880 |
CAVV decline. Exceeds the maximum auth cashback amount limit. |
1881 |
Exceeds max auth cashback amount limit. |
1882 |
CVV attempt limit exceeded. |
1883 |
JIT response invalid amount. |
1884 |
JIT response not sufficient funds. |
1885 |
JIT response transaction not permitted. |
1886 |
JIT response suspected fraud. |
1887 |
JIT response amount limit reached. |
1888 |
JIT response usage limit reached. |
1889 |
JIT response duplicate entry. |
1890 |
Low device score. |
1891 |
Strong Customer Authentication — SCA contactless cumulative amount exceeded. |
1892 |
Strong Customer Authentication — SCA contactless transaction count limit exceeded. |
1893 |
Strong Customer Authentication — SCA contactless transaction limit exceeded. |
1894 |
Card account verification decline. |
1895 |
Token activation request — STIP decline. |
1896 |
Token activation request card product config decline. |
1897 |
SCA LVP cumulative amount exceeded. |
1898 |
SCA LVP transaction count limit exceeded. |
1899 |
SCA LVP transaction limit exceeded. |
1900 |
Rejected response. |
1901 |
Card not activated. |
1902 |
JIT response invalid merchant. |
1903 |
JIT response invalid card. |
1904 |
JIT response no credit account. |
1905 |
JIT response expired card. |
1906 |
JIT response no checking account. |
1907 |
JIT response no savings account. |
1908 |
JIT response stop payment. |
1909 |
JIT response revocation authorization order. |
1910 |
JIT response revocation all authorization order. |
1911 |
JIT response soft decline authentication required. |
1912 |
JIT response closed account. |
1913 |
Transaction not allowed in a limited state. |
1914 |
Chip data missing required fields. |
1915 |
Invalid CVV2. |
1916 |
Consecutive CVV failure suspected fraud. |
1918 |
JIT Response soft decline PIN required. |
1919 |
Card terminated. |
1920 |
Cardholder terminated. |
1921 |
Digital wallet token terminated. |
1922 |
Transaction cannot be completed. |
1923 |
Not sufficient funds - no cached balance. |
1924 |
Installment payment not supported in this region. |
1925 |
JIT response card not active. |
1926 |
JIT response cardholder not active. |
1927 |
Account transfer not allowed |
The transaction lifecycle
Copy section link
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.
How 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, 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:
-
The card network sends an authorization message for $100 to the Marqeta platform. The Marqeta platform creates a
transactionobject A of typeauthorizationin aPENDINGstate and puts a temporary hold on $100 for object A. -
The card network sends a clearing message for $40 to the Marqeta platform. The Marqeta platform creates a
transactionobject B of typeclearingin aCOMPLETIONstate (related to the object A), puts a final hold on $40 for object B, and updates the temporary hold to $60 for object A. -
The card network sends a clearing message for $20 to the Marqeta platform. The Marqeta platform creates a
transactionobject C of typeclearingin aCOMPLETIONstate (related to the objects A and B), puts a final hold on $20 for object C, and updates the temporary hold to $40 for object A. -
The card network sends a reversal message for $40 to the Marqeta platform. The Marqeta platform creates a
transactionobject D of typereversalin aCLEAREDstate (related to the objects A, B, and C), releases the hold on $40 for object D, updates the temporary hold to $0 for object A, and transitions object A to aCLEAREDstate.
