Transactions
The
You can receive information about transactions as they occur by configuring webhooks. Learn about configuring webhooks in the Webhooks Overview page. See the transaction events for which you can set up webhooks in the Event Types page.
You can also retrieve transactions associated with specific cards, merchants, and account holders using the endpoints described here.
Note
Use the
Retrieve transaction
Copy section link
Action:
Endpoint:
Retrieve a specific transaction. Include the
Note
Transactions are not available in real time through this endpoint, but typically appear after 30 seconds. On occasion, however, a transaction may require up to four hours to appear.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the transaction to retrieve. Allowable Values: Existing transaction token |
Transaction field descriptions
Copy section link
The following table contains a superset of possible response elements. Responses always include the
Field | Description |
---|---|
token |
Unique identifier of the transaction, formatted as a UUID. |
identifier |
Sequential identifier of the transaction. |
user_token |
Unique identifier of the user who owns the account that funded the transaction; subsequent related transactions retain the same user_token even if the card used for the transaction moves to another user. |
business_token |
Unique identifier of the business that owns the account that funded the transaction. |
acting_user_token |
Unique identifier of the user who conducted the transaction. The user can be a child user configured to share its parent’s account balance. |
card_token |
Unique identifier of the card. Useful when a single account holder has multiple cards. |
type |
Represents the transaction type. For more information about the type field, see the "Transaction events" section on the Event Types page. |
state |
The current state of the transaction, either PENDING , CLEARED , COMPLETION , DECLINED or ERROR . For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.
|
network_reference_id |
Network-assigned unique identifier of the transaction. Useful for settlement and reconciliation. |
duration |
Duration of the transaction on Marqeta servers, in milliseconds. |
created_time |
Date and time when the Marqeta platform created the transaction entry (for example, when the platform received an incoming message for a refund). |
user_transaction_time |
Date and time when the user initiated the transaction (for example, when a merchant entered a refund). |
issuer_received_time |
Date and time when the Marqeta platform received the transaction from the card network. |
settlement_date |
Date and time when funds were moved for a transaction (for example, in the case of a refund, when funds were credited to the cardholder). |
issuer_payment_node |
Identifier of the Marqeta platform server that received the transaction from the card network. |
request_amount |
Used for clearing/settling transactions to compare to the original authorization amount. |
amount |
Amount of the transaction. |
cash_back_amount |
Amount of cashback included in the total transaction amount. Only included in pindebit.cashback transactions.
|
currency_code |
The three-character ISO 4217 currency type of the transaction. |
approval_code |
The unique ID assigned to a given authorization. Is printed on the receipt at point of sale. |
response |
Object containing information about the response, including the response code and response memo. |
preceding_related_transaction_token |
Returned for final transaction types. Unique identifier of the preceding related transaction. Useful for identifying the temporary transaction completed by the current transaction. For example, authorization , a temporary transaction type, precedes and is completed by authorization.clearing , a final transaction type. In this case, the authorization token is returned with this field. For which transaction types are temporary or final, see Transaction events in Event Types.
|
preceding_transaction |
Returned for authorization.clearing transaction types following a financial advice.
Object containing the amount and token of the preceding authorization transaction.
|
amount_to_be_released |
Returned for authorization.clearing transaction types following a financial advice.
Amount to release following an advice. |
merchant |
Object containing information about the merchant, including whether partial authorizations are allowed. |
card_acceptor |
Object containing information about the card acceptor, such as the MID, MCC, or MCC group. |
gpa |
Object containing information about the GPA balances and pending credits. |
gpa_order_unload |
Object containing information about a GPA order unload. A GPA order unload unloads funds from a card and returns it to the funding source. |
gpa_order |
Object containing information about a GPA order, including fees, funding sources, and addresses. See Orders for more information. |
program_transfer |
Object containing information about a program transfer. |
fee_transfer |
Object containing information about a fee transfer, including the amount, the currency code, and user or business token. See Transfers for more information. |
peer_transfer |
Object containing information about a peer transfer, including sender and recipient tokens, transfer amount and currency code. See Transfers for more information. |
risk_assessment |
Object containing information about risk assessments. |
auto_reload |
Object containing information about auto reloads. See Auto Reloads for more information. |
direct_deposit |
Object containing information about a direct deposit. See Direct Deposits for more information. |
polarity |
Object indicating whether the transaction is credit or debit. |
real_time_fee_group |
Object containing information about a realtime fee group. |
fee |
Object containing information about fees related to the transaction. |
chargeback |
Contains the chargeback object associated with this transaction if a chargeback has been initiated. |
network |
Indicates which card network was used for the transaction (DISCOVER, MASTERCARD, PULSE, VISA, and MARQETA). |
subnetwork |
Indicates which subnetwork was used for the transaction. Possible values include the following:
|
standin_approved_by |
Indicates which party approved a transaction requiring stand-in processing or Commando Mode. Returned only when a transaction is approved. |
standin_by |
Indicates which party handled a transaction requiring stand-in processing or Commando Mode. |
standin_reason |
Indicates why the network handled a transaction requiring stand-in processing. Not returned unless transaction is declined. |
acquirer_fee_amount |
Indicates the amount of the acquirer fee. Account holders are sometimes charged an acquirer fee for card use at ATMs, fuel dispensers, etc. |
user |
Contains customer-injected metadata associated with the account holder who funded the transaction. |
digital_wallet_token |
Contains the entire digital_wallet_token object; present for all transactions funded by way of a digital wallet or related to digital wallet token provisioning. |
network_fees |
Contains card network fees assessed against the cardholder. |
card_security_code_verification |
Object containing information about a verification check performed on the card’s security code. The nested type field indicates the type of security code and can have these possible values:
The nested response.code field indicates whether the verification check passed and can have these possible values:
|
pos |
Object containing information about the point of sale, including details about how the card was presented. |
avs |
Object containing Address Verification System (AVS) data provided by the merchant. |
acquirer |
Object containing information about the merchant’s financial institution. |
transaction_metadata |
Object containing merchant-provided metadata related to the transaction, including details about lodging and transit-related purchases. |
fraud |
Object containing one or more fraud determinations for the transaction and the cardholder’s account; this object can contain fraud determinations calculated by the card network and issuer-processor (Marqeta). |
cardholder_authentication_data |
Object containing 3D Secure verification data:
|
currency_conversion |
Object containing information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate. |
original_credit |
Object containing information about an original credit transaction (OCT), including the transaction type, source of funds, sender name, and screening score. |
The currency_conversion object
Copy section link
Fields | Description |
---|---|
network
object
|
Object containing information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate. Allowable Values: See the currency_conversion.network object table. |
The currency_conversion.network object
Copy section link
Fields | Description |
---|---|
original_amount
decimal
|
Object containing information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate. Allowable Values: Decimal amount. |
conversion_rate
decimal
|
Conversion rate when clearing transactions in a currency different than billing currency. Allowable Values: Current conversion rate |
original_currency_code
string
|
The original three-character ISO 4217 currency type of the transaction. Allowable Values: The three-character ISO 4217 currency type. |
dynamic_currency_conversion
boolean
|
Indicates if currency conversion was performed at the point of sale. Allowable Values: true , false
Default value: false
|
The following sample shows a
List transactions
Copy section link
Action:
Endpoint:
List all transactions.
By default, this endpoint returns transactions conducted within the last 30 days. To return transactions older than 30 days, you must include the
By default,
This endpoint supports field filtering and pagination.
Query parameters
Copy section link
Fields | Description |
---|---|
start_date
string
|
The starting date (or date-time) of a date range from which to return transactions. To return transactions for a single day, enter the same date in both the start_date and end_date fields.
Allowable Values: yyyy-MM-dd OR yyyy-MM-dd’T’HH:mm:ss.SSSZ Default value: |
end_date
string
|
The ending date (or date-time) of a date range from which to return transactions. To return transactions for a single day, enter the same date in both the end_date and start_date fields.
Allowable Values: yyyy-MM-dd Default value: |
type
string
|
Returns transactions of the specified types. Allowable Values: Comma-delimited list of transaction types. To return all types, leave blank. Default value: See Event Types for a list of transaction types. |
state
string
|
Returns transactions of the specified state. For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page. Allowable Values: Comma-delimited list of transaction states: PENDING , CLEARED , COMPLETION , DECLINED , ERROR , ALL
Default value: PENDING , COMPLETION
|
user_token
string
|
Enter a user token to return transactions conducted by that user. In the case of a parent user, transactions conducted by the parent and all children configured to share the parent’s account balance are returned. Entering the token of a child user who is configured to share the parent’s account balances returns zero transactions. Allowable Values: Existing user token. Send a GET request to /users to retrieve user tokens.
|
business_token
string
|
Enter a business token to return transactions conducted by that business' children and grandchildren users. Allowable Values: Existing business token. Send a GET request to /businesses to retrieve business tokens.
|
acting_user_token
string
|
Enter a user token to return transactions conducted only by that user. This parameter is useful in the case of a parent with children configured to share the parent’s account balance. In this case, entering the parent’s user token returns only transactions conducted by the parent; entering a child’s user token returns only transactions conducted by the child. Allowable Values: Existing user token. Send a GET request to /users to retrieve user tokens.
NoteThis parameter does not accept business tokens. |
card_token
string
|
Enter a card token to return transactions for a specific card. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
|
merchant_token
string
|
Enter a merchant token to return transactions for a specific merchant. Allowable Values: Existing merchant token. Send a GET request to /merchants to retrieve merchant tokens.
|
campaign_token
string
|
Enter a campaign token to return transactions for a specific campaign. Allowable Values: Existing campaign token. Send a GET request to /campaigns to retrieve campaign tokens.
|
List related transactions
Copy section link
Action:
Endpoint:
List all transactions related to the specified transaction.
By default, this endpoint returns transactions conducted within the last 30 days. To return transactions older than 30 days, you must include the
By default, this endpoint returns transactions of any state. To return transactions in specific states, you must include the
This endpoint supports field filtering and pagination.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the transaction whose related transactions you want to retrieve. Allowable Values: Existing transaction token |
Query parameters
Copy section link
Fields | Description |
---|---|
start_date
string
|
The starting date (or date-time) of a date range from which to return transactions. To return transactions for a single day, enter the same date in both the start_date and end_date fields.
Allowable Values: yyyy-MM-dd OR yyyy-MM-dd’T’HH:mm:ss.SSSZ Default value: |
end_date
string
|
The ending date (or date-time) of a date range from which to return transactions. To return transactions for a single day, enter the same date in both the end_date and start_date fields.
Allowable Values: yyyy-MM-dd Default value: |
type
string
|
Returns transactions of the specified types. Allowable Values: Comma-delimited list of transaction types. To return all types, leave blank. Default value: See Transaction Types for a list of transaction types. |
state
string
|
Returns transactions of the specified state. For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page. Allowable Values: Comma-delimited list of transaction states: PENDING , CLEARED , COMPLETION , DECLINED , ERROR , ALL
|
Reverse authorization
Copy section link
Action:
Endpoint:
Reverse a pending authorization. Include the token identifying the transaction you want to reverse in JSON format in the body of the request.
Body field details
Copy section link
Fields | Description |
---|---|
original_transaction_token
string
|
Identifies the transaction to reverse. Allowable Values: Existing transaction token. Send a GET request to /transactions to retrieve transaction tokens.
|
Transaction response codes
Copy section link
You can use the
-
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 codes table
Copy section link
Code | Description |
---|---|
0000 |
Transaction approved or completed successfully. |
0002 |
Partially approved. |
1001 |
Card expired. |
1002 |
Card suspicious. Expiration mismatch. |
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 |
FraudStream decision declines transaction. |
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. |