Transactions

The /transactions resource represents the electronic messages that carry information used for payment processing. A transaction usually originates when a card holder attempts to make a payment online or at a physical point of sale.

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 /transactions endpoint to retrieve smaller datasets (up to one page). For best performance when requesting larger datasets, use the DiVA API.

For an overview of transactions and the transaction object, see About Transactions.

Retrieve transaction

Action: GET
Endpoint: /transactions/{token}

Retrieve a specific transaction. Include the token path parameter to identify the transaction.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the transaction to retrieve. Existing transaction token

Transaction field descriptions

The following table contains a superset of possible response elements. Responses always include the type and amount fields. Other objects are conditionally returned. For more information about which objects may be returned based on the type of transaction, see the Transaction Types table.

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, or DECLINED. For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.
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 card holder).
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 cash back included in the total transaction amount. Only included in pindebit.cashback transactions.
currency_code The 3-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 For non-pending transaction types, some previous transaction will be referenced. For example, an authorization.reversal or authorization.clearing may affect an authorization. This element is omitted for "pending" transaction types such as gpa.credit.pending and authorization. See Transaction Types for information on which transaction types are "pending".
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/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.
msa_orders An array of objects containing information about MSA orders, including order balances, and purchase and funding information. See Orders 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:
  • VISANET – Used for VisaNet signature-based transactions.
  • VISANETDEBIT – Used for VisaNet Debit PIN-based transaction.
  • VISAINTERLINK – Used for Visa Interlink PIN-based transactions.
  • VISAPLUS – Used for ATM withdrawals on Visa.
  • MAESTRO – Used for PIN-based transactions on Mastercard.
  • CIRRUS – Used for ATM withdrawals on Mastercard.
  • MASTERCARDDEBIT – Used for signature-based transactions on Mastercard.
  • GATEWAY_JIT – Used for Gateway JIT Funding transactions.
  • MANAGED_JIT – Used for Managed JIT Funding transactions or for transactions that occur while Commando Mode is enabled.
standin_approved_by Indicates which party handled a transaction requiring stand-in processing or Commando Mode. Returned only when a transaction is approved.
standin_by Indicates that a transaction required stand-in processing or Commando Mode.
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 card holder.
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:
  • CVV1 – the security code stored in the magnetic stripe on the card.
  • CVV2 – the security code printed on the card.
  • ICVV – the security code stored on the chip of the card.
  • DCVV – a dynamic security code used in some contactless payments when a card or device is tapped against the card reader.
The nested "response.code" field indicates whether the verification check passed and can have these possible values:
  • 0000 – passed
  • 0001 – did not pass
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 card holder's account; this object can contain fraud determinations calculated by the card network and issuer-processor (Marqeta).
cardholder_authentication_data Object containing 3-D Secure verification data:
  • electronic_commerce_indicator – The level of verification performed.
  • verification_result – The result of the verification.
  • verification_value_created_by – The transaction participant who determined the verification result.
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

Name Type Always Included? Description Potential Values
network object No 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.

The currency_conversion.network object

Name Type Always Included? Description Potential Values
original_amount decimal No 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. Decimal amount.
conversion_rate decimal No Conversion rate when clearing transactions in a currency different than billing currency. Current conversion rate

Note: A value of 0 or 1 indicates no conversion; the currencies are the same.
original_currency_code string No The original 3-character ISO 4217 currency type of the transaction. 3-character ISO 4217 currency type.

The following sample shows a currency_conversion.network object when the transaction currency is in EUR and the billing currency is in USD.

"amount": 14.53,
   "currency_conversion": {
   "network": {
      "original_amount": 12.85,
      "conversion_rate": 1.13049,
      "original_currency_code": "978"
  }
},

Sample response body

{
    "type": "authorization",
    "state": "PENDING",
    "token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
"identifier": "1201",
    "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
    "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
    "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
    "gpa": {
        "currency_code": "USD",
        "ledger_balance": 20,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -10,
        "balances": {
            "USD": {
                "currency_code": "USD",
                "ledger_balance": 20,
                "available_balance": 0,
                "credit_balance": 0,
                "pending_credits": 0,
                "impacted_amount": -10
            }
        }
    },
    "gpa_order": {
        "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
        "amount": 10,
        "created_time": "2018-08-21T17:26:30Z",
        "last_modified_time": "2018-08-21T17:26:30Z",
        "transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
        "state": "PENDING",
        "response": {
            "code": "0000",
            "memo": "Approved or completed successfully"
        },
        "funding": {
            "amount": 10,
            "source": {
                "type": "programgateway",
                "token": "**********dd5f",
                "active": true,
                "name": "PGFS for simulating transactions",
                "is_default_account": false,
                "created_time": "2018-08-21T17:25:43Z",
                "last_modified_time": "2018-08-21T17:25:43Z"
            },
            "gateway_log": {
                "order_number": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
                "transaction_id": "your-jit-funding-token",
                "message": "Approved or completed successfully",
                "duration": 481,
                "timed_out": false,
                "response": {
                    "code": "200",
                    "data": {
                        "jit_funding": {
                            "token": "your-jit-funding-token",
                            "method": "pgfs.authorization",
                            "user_token": "your-jit-funding-user",
                            "amount": 10,
                            "original_jit_funding_token": "your-jit-funding-token",
                            "address_verification": {
                                "gateway": {
                                    "on_file": {
                                        "street_address": "2000 High St",
                                        "postal_code": "94601"
                                    },
                                    "response": {
                                        "code": "0000",
                                        "memo": "Address and postal code match"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "funding_source_token": "**********dd5f",
        "jit_funding": {
            "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
            "method": "pgfs.authorization",
            "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "amount": 10
        },
        "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
        "currency_code": "USD"
    },
    "duration": 622,
    "created_time": "2018-08-21T17:26:29Z",
    "user_transaction_time": "2018-08-21T17:26:29Z",
"issuer_received_time": "2018-08-21T17:26:29Z",
    "settlement_date": "2018-08-21T00:00:00Z",
"issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
    "request_amount": 10,
    "amount": 10,
    "currency_conversion": {
"network": {
    "original_amount": 10,
    "conversion_rate": 1.000000,
    "original_currency_code": "840"
        }
    },
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "761515",
    "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
        "institution_country": "840",
        "institution_id_code": "428399181",
        "retrieval_reference_number": "528294182583",
        "system_trace_audit_number": "656761"
    },
    "user": {
        "metadata": {}
    },
    "card": {
        "metadata": {}
    },
    "card_security_code_verification": {
        "type": "CVV1",
        "response": {
            "code": "0000",
            "memo": "Card security code match"
        }
    },
    "fraud": {
        "network": {
            "transaction_risk_score": 97,
            "account_risk_score": 7
        },
"issuer_processor":{
"score": "64",
"risk_level": "MEDIUM",
"recommended_action": "APPROVE",
"rule_violations":
[
"24hr.velocity.exceeded"
]
}
},
"cardholder_authentication_data": {
"electronic_commerce_indicator": "authentication_successful",
"verification_result": "verified",
"verification_value_created_by": "issuer_acs"
},
    "card_acceptor": {
        "mid": "000000000011111",
        "mcc": "6411",
        "name": "Chicken Tooth Music",
"street_address": "111 Main St",
        "city": "Berkeley",
        "country_code": "USA"
    },
    "pos": {
        "pan_entry_mode": "MAG_STRIPE",
        "pin_entry_mode": "TRUE",
        "terminal_id": "TR100000",
        "terminal_attendance": "ATTENDED",
        "card_holder_presence": false,
        "card_presence": false,
        "partial_approval_capable": false,
        "purchase_amount_only": false,
        "is_recurring": false
    },
    "transaction_metadata": {
        "payment_channel": "OTHER"
    }
}


List transactions

Action: GET
Endpoint: /transactions

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 start_date and end_date query parameters in your request.

By default, GET /transactions returns transactions having PENDING or COMPLETION states.

This endpoint supports field filtering and pagination.

Query parameters

Name Type Required? Description Allowable Values
start_date string No 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.
yyyy-MM-dd

OR

yyyy-MM-dd’T’HH:mm:ss.SSSZ

Default: current date minus 30 days (the time of day is not factored in).
end_date string No 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.
yyyy-MM-dd

Default: current date (the time of day is not factored in).
type string No Returns transactions of the specified types. Comma-delimited list of transaction types.

To return all types, leave blank.

Default: All types (blank)

See Transaction Types for a list of transaction types.
state string No Returns transactions of the specified state.

For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.
Comma-delimited list of transaction states:

PENDING, CLEARED, COMPLETION, DECLINED, ALL

Default: PENDING, COMPLETION
user_token string No 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. Existing user token.

Issue a GET to /users to retrieve user tokens.
business_token string No Enter a business token to return transactions conducted by that business's children and grandchildren users. Existing business token.

Issue a GET to /businesses to retrieve business tokens.
acting_user_token string No 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. Existing user token.

Issue a GET to /users to retrieve user tokens.

Note: This parameter does not accept business tokens.
card_token string No Enter a card token to return transactions for a specific card. Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a specific user.
merchant_token string No Enter a merchant token to return transactions for a specific merchant. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.
campaign_token string No Enter a campaign token to return transactions for a specific campaign. Existing campaign token.

Issue a GET to /campaigns to retrieve campaign tokens.

Sample response body

{
    "count": 2,
    "start_index": 0,
    "end_index": 1,
    "is_more": true,
    "data": [
        {
            "type": "gpa.credit.authorization",
            "state": "PENDING",
            "token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
"identifier": "1202",
            "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
            "preceding_related_transaction_token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
            "gpa": {
                "currency_code": "USD",
                "ledger_balance": 20,
                "available_balance": 0,
                "credit_balance": 0,
                "pending_credits": 0,
                "impacted_amount": 10,
                "balances": {
                    "USD": {
                        "currency_code": "USD",
                        "ledger_balance": 20,
                        "available_balance": 0,
                        "credit_balance": 0,
                        "pending_credits": 0,
                        "impacted_amount": 10
                    }
                }
            },
            "gpa_order": {
                "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
                "amount": 10,
                "created_time": "2018-08-21T17:26:30Z",
                "last_modified_time": "2018-08-21T17:26:30Z",
                "transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
                "state": "PENDING",
                "response": {
                    "code": "0000",
                    "memo": "Approved or completed successfully"
                },
                "funding": {
                    "amount": 10,
                    "source": {
                        "type": "programgateway",
                        "token": "**********dd5f",
                        "active": true,
                        "name": "PGFS for simulating transactions",
                        "is_default_account": false,
                        "created_time": "2018-08-21T17:25:43Z",
                        "last_modified_time": "2018-08-21T17:25:43Z"
                    },
                    "gateway_log": {
                        "order_number": "1200",
                        "transaction_id": "your-jit-funding-token",
                        "message": "Approved or completed successfully",
                        "duration": 481,
                        "timed_out": false,
                        "response": {
                            "code": "200",
                            "data": {
                                "jit_funding": {
                                    "token": "your-jit-funding-token",
                                    "method": "pgfs.authorization",
                                    "user_token": "your-jit-funding-user",
                                    "amount": 10,
                                    "original_jit_funding_token": "your-jit-funding-token",
                                    "address_verification": {
                                        "gateway": {
                                            "on_file": {
                                                "street_address": "2000 High St",
                                                "postal_code": "94601"
                                            },
                                            "response": {
                                                "code": "0000",
                                                "memo": "Address and postal code match"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "funding_source_token": "**********dd5f",
                "jit_funding": {
                    "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
                    "method": "pgfs.authorization",
                    "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                    "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                    "amount": 10
                },
                "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                "currency_code": "USD"
            },
            "duration": 537,
            "created_time": "2018-08-21T17:26:29Z",
            "issuer_received_time": "2018-08-21T17:26:29Z",
            "user_transaction_time": "2018-08-21T17:26:29Z",
"issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
            "amount": 10,
            "currency_code": "USD",
            "response": {
                "code": "0000",
                "memo": "Approved or completed successfully"
            },
            "network": "MARQETA",
            "subnetwork": "GATEWAY_JIT",
            "acquirer": {
                "institution_country": "840",
                "institution_id_code": "428399181",
                "retrieval_reference_number": "528294182583",
                "system_trace_audit_number": "656761"
            },
            "user": {
                "metadata": {}
            },
            "card": {
                "metadata": {}
            },
            "card_security_code_verification": {
                "type": "CVV1",
                "response": {
                    "code": "0000",
                    "memo": "Card security code match"
                }
            },
            "fraud": {
                "network": {
                    "transaction_risk_score": 97,
                    "account_risk_score": 7
                }
            },
            "pos": {
                "pan_entry_mode": "MAG_STRIPE",
                "pin_entry_mode": "TRUE",
                "terminal_attendance": "ATTENDED",
                "card_holder_presence": false,
                "card_presence": false,
                "partial_approval_capable": false,
                "purchase_amount_only": false,
                "is_recurring": false
            },
            "transaction_metadata": {
                "payment_channel": "OTHER"
            }
        },
        {
            "type": "authorization",
            "state": "PENDING",
            "token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
"identifier": "1201",
            "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
            "gpa": {
                "currency_code": "USD",
                "ledger_balance": 20,
                "available_balance": 0,
                "credit_balance": 0,
                "pending_credits": 0,
                "impacted_amount": -10,
                "balances": {
                    "USD": {
                        "currency_code": "USD",
                        "ledger_balance": 20,
                        "available_balance": 0,
                        "credit_balance": 0,
                        "pending_credits": 0,
                        "impacted_amount": -10
                    }
                }
            },
            "gpa_order": {
                "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
                "amount": 10,
                "created_time": "2018-08-21T17:26:30Z",
                "last_modified_time": "2018-08-21T17:26:30Z",
                "transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
                "state": "PENDING",
                "response": {
                    "code": "0000",
                    "memo": "Approved or completed successfully"
                },
                "funding": {
                    "amount": 10,
                    "source": {
                        "type": "programgateway",
                        "token": "**********dd5f",
                        "active": true,
                        "name": "PGFS for simulating transactions",
                        "is_default_account": false,
                        "created_time": "2018-08-21T17:25:43Z",
                        "last_modified_time": "2018-08-21T17:25:43Z"
                    },
                    "gateway_log": {
                        "order_number": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
                        "transaction_id": "your-jit-funding-token",
                        "message": "Approved or completed successfully",
                        "duration": 481,
                        "timed_out": false,
                        "response": {
                            "code": "200",
                            "data": {
                                "jit_funding": {
                                    "token": "your-jit-funding-token",
                                    "method": "pgfs.authorization",
                                    "user_token": "your-jit-funding-user",
                                    "amount": 10,
                                    "original_jit_funding_token": "your-jit-funding-token",
                                    "address_verification": {
                                        "gateway": {
                                            "on_file": {
                                                "street_address": "2000 High St",
                                                "postal_code": "94601"
                                            },
                                            "response": {
                                                "code": "0000",
                                                "memo": "Address and postal code match"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "funding_source_token": "**********dd5f",
                "jit_funding": {
                    "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
                    "method": "pgfs.authorization",
                    "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                    "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                    "amount": 10
                },
                "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                "currency_code": "USD"
            },
            "duration": 622,
            "created_time": "2018-08-21T17:26:29Z",
            "issuer_received_time": "2018-08-21T17:26:29Z",
            "user_transaction_time": "2018-08-21T17:26:29Z",
            "settlement_date": "2018-08-21T00:00:00Z",
"issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
            "request_amount": 10,
            "amount": 10,
            "currency_code": "USD",
            "approval_code": "761515",
            "response": {
                "code": "0000",
                "memo": "Approved or completed successfully"
            },
            "network": "VISA",
            "subnetwork": "VISANET",
            "acquirer_fee_amount": 0,
            "acquirer": {
                "institution_country": "840",
                "institution_id_code": "428399181",
                "retrieval_reference_number": "528294182583",
                "system_trace_audit_number": "656761"
            },
            "user": {
                "metadata": {}
            },
            "card": {
                "metadata": {}
            },
            "card_security_code_verification": {
                "type": "CVV1",
                "response": {
                    "code": "0000",
                    "memo": "Card security code match"
                }
            },
            "fraud": {
                "network": {
                    "transaction_risk_score": 97,
                    "account_risk_score": 7
                }
            },
            "card_acceptor": {
                "mid": "000000000011111",
                "mcc": "6411",
                "name": "Chicken Tooth Music",
"street_address": "111 Main St",
                "city": "Berkeley",
                "country_code": "USA"
            },
            "pos": {
                "pan_entry_mode": "MAG_STRIPE",
                "pin_entry_mode": "TRUE",
                "terminal_id": "TR100000",
                "terminal_attendance": "ATTENDED",
                "card_holder_presence": false,
                "card_presence": false,
                "partial_approval_capable": false,
                "purchase_amount_only": false,
                "is_recurring": false
            },
            "transaction_metadata": {
                "payment_channel": "OTHER"
            }
        }
    ]
}


List related transactions

Action: GET
Endpoint: /transactions/{token}/related

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 start_date and end_date query parameters in your request.

By default, this endpoint returns transactions of any state. To return transactions in specific states, you must include the state query parameter in your request.

This endpoint supports field filtering and pagination.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the transaction whose related transactions you want to retrieve. Existing transaction token

Query parameters

Name Type Required? Description Allowable Values
start_date string No 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.
yyyy-MM-dd

OR

yyyy-MM-dd’T’HH:mm:ss.SSSZ

Default: current date minus 30 days (the time of day is not factored in).
end_date string No 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.
yyyy-MM-dd

Default: current date (the time of day is not factored in).
type string No Returns transactions of the specified types. Comma-delimited list of transaction types.

To return all types, leave blank.

Default: All types (blank)

See Transaction Types for a list of transaction types.
state string No Returns transactions of the specified state.

For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.
Comma-delimited list of transaction states:

PENDING, CLEARED, COMPLETION, DECLINED, ALL

Sample response body

{
    "count": 1,
    "start_index": 0,
    "end_index": 0,
    "is_more": false,
    "data": [
        {
            "type": "gpa.credit.authorization",
            "state": "PENDING",
            "token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
"identifier": "1202",
            "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
            "preceding_related_transaction_token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
            "gpa": {
                "currency_code": "USD",
                "ledger_balance": 20,
                "available_balance": 0,
                "credit_balance": 0,
                "pending_credits": 0,
                "impacted_amount": 10,
                "balances": {
                    "USD": {
                        "currency_code": "USD",
                        "ledger_balance": 20,
                        "available_balance": 0,
                        "credit_balance": 0,
                        "pending_credits": 0,
                        "impacted_amount": 10
                    }
                }
            },
            "gpa_order": {
                "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
                "amount": 10,
                "created_time": "2018-08-21T17:26:30Z",
                "last_modified_time": "2018-08-21T17:26:30Z",
                "transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
                "state": "PENDING",
                "response": {
                    "code": "0000",
                    "memo": "Approved or completed successfully"
                },
                "funding": {
                    "amount": 10,
                    "source": {
                        "type": "programgateway",
                        "token": "**********dd5f",
                        "active": true,
                        "name": "PGFS for simulating transactions",
                        "is_default_account": false,
                        "created_time": "2018-08-21T17:25:43Z",
                        "last_modified_time": "2018-08-21T17:25:43Z"
                    },
                    "gateway_log": {
                        "order_number": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
                        "transaction_id": "your-jit-funding-token",
                        "message": "Approved or completed successfully",
                        "duration": 481,
                        "timed_out": false,
                        "response": {
                            "code": "200",
                            "data": {
                                "jit_funding": {
                                    "token": "your-jit-funding-token",
                                    "method": "pgfs.authorization",
                                    "user_token": "your-jit-funding-user",
                                    "amount": 10,
                                    "original_jit_funding_token": "your-jit-funding-token",
                                    "address_verification": {
                                        "gateway": {
                                            "on_file": {
                                                "street_address": "2000 High St",
                                                "postal_code": "94601"
                                            },
                                            "response": {
                                                "code": "0000",
                                                "memo": "Address and postal code match"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "funding_source_token": "**********dd5f",
                "jit_funding": {
                    "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
                    "method": "pgfs.authorization",
                    "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                    "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                    "amount": 10
                },
                "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
                "currency_code": "USD"
            },
            "duration": 537,
            "created_time": "2018-08-21T17:26:29Z",
            "issuer_received_time": "2018-08-21T17:26:29Z",
            "user_transaction_time": "2018-08-21T17:26:29Z",
"issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
            "amount": 10,
            "currency_code": "USD",
            "response": {
                "code": "0000",
                "memo": "Approved or completed successfully"
            },
            "network": "MARQETA",
            "subnetwork": "GATEWAY_JIT",
            "acquirer": {
                "institution_country": "840",
                "institution_id_code": "428399181",
                "retrieval_reference_number": "528294182583",
                "system_trace_audit_number": "656761"
            },
            "user": {
                "metadata": {}
            },
            "card": {
                "metadata": {}
            },
            "card_security_code_verification": {
                "type": "CVV1",
                "response": {
                    "code": "0000",
                    "memo": "Card security code match"
                }
            },
            "fraud": {
                "network": {
                    "transaction_risk_score": 97,
                    "account_risk_score": 7
                }
            },
            "pos": {
                "pan_entry_mode": "MAG_STRIPE",
                "pin_entry_mode": "TRUE",
                "terminal_attendance": "ATTENDED",
                "card_holder_presence": false,
                "card_presence": false,
                "partial_approval_capable": false,
                "purchase_amount_only": false,
                "is_recurring": false
            },
            "transaction_metadata": {
                "payment_channel": "OTHER"
            }
        }
    ]
}


Reverse authorization

Action: POST
Endpoint: /transactions/authorizationreversal

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

Name Type Required? Description Allowable Values
original_transaction_token string Yes Identifies the transaction to reverse. Existing transaction token.

Issue a GET to /transactions to retrieve transaction tokens.

Sample request body

{
"original_transaction_token": "cd22cff7-2845-4508-a916-cf89fd9edae1"
}

Sample response body

{
    "type": "authorization.reversal",
    "state": "CLEARED",
    "token": "4114a1dd-bb65-4cf6-924c-bac24e49bf16",
"identifier": "1207",
    "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
    "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
    "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
    "preceding_related_transaction_token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
    "gpa": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 10,
        "balances": {
            "USD": {
                "currency_code": "USD",
                "ledger_balance": 10,
                "available_balance": 0,
                "credit_balance": 0,
                "pending_credits": 0,
                "impacted_amount": 10
            }
        }
    },
    "gpa_order": {
        "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
        "amount": 10,
        "created_time": "2018-08-21T17:26:30Z",
        "last_modified_time": "2018-08-21T17:45:09Z",
        "transaction_token": "0ff203cc-e31c-4e74-a5d4-5fc9009daa9d",
        "state": "REVERSED",
        "response": {
            "code": "0000",
            "memo": "Approved or completed successfully"
        },
        "funding": {
            "amount": 10,
            "source": {
                "type": "programgateway",
                "token": "**********dd5f",
                "active": true,
                "name": "PGFS for simulating transactions",
                "is_default_account": false,
                "created_time": "2018-08-21T17:25:43Z",
                "last_modified_time": "2018-08-21T17:25:43Z"
            }
        },
        "funding_source_token": "**********dd5f",
        "jit_funding": {
            "token": "1600b3fe-8731-4f15-b26b-3f12b467d2e7",
            "method": "pgfs.authorization.reversal",
            "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
            "amount": 10,
            "original_jit_funding_token": "your-jit-funding-token"
        },
        "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
        "currency_code": "USD"
    },
    "duration": 166,
    "created_time": "2018-08-21T17:45:09Z",
    "issuer_received_time": "2018-08-21T17:26:29Z",
"issuer_payment_node": "b9a60cd41a2cc1c23090ed3666bdbf1z",
    "user_transaction_time": "2018-08-21T17:26:29Z",
    "request_amount": 10,
    "amount": 10,
    "currency_code": "USD",
    "approval_code": "761515",
    "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
        "system_trace_audit_number": "656761"
    },
    "user": {
        "metadata": {}
    },
    "card": {
        "metadata": {}
    },
    "card_acceptor": {
        "mid": "000000000011111",
        "mcc": "6411",
        "name": "Chicken Tooth Music",
"street_address": "111 Main St",
        "city": "Berkeley",
        "country_code": "USA"
    },
    "pos": {
        "partial_approval_capable": false,
        "purchase_amount_only": false,
        "is_recurring": false
    }
}


Transaction response codes

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=authorization and response.code=1001 indicates a card authorization attempt that failed because the card was expired.
  • A combination of type=authorization or type=pindebit with a response.code of 0000, 0002, or 1830 indicates a successful transaction. All other response codes indicate a failed transaction.

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 page.

Response codes table

Code Description
0000 Approved or completed successfully.
0002 Partially approved.
1001 Card expired.
1002 Card suspicious. Expiration mismatch.
1003 The card has been suspended.
1004 Card stolen - pickup.
1005 Card lost.
1011 Card is not in the Marqeta database.
1012 The cardholder does not exist in the Marqeta database. Possible that card is valid but cardholder has not been created.
1014 The account was not created for the currency in the transaction.
1015 Request cannot be parsed, or relevant data not found.
1016 Insufficient funds in account for 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 PAN information missing from 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 cannot be found.
1813 Cardholder not active. Transaction occurs outside the card start and end dates.
1814 Start and end dates have not been configured for the cardholder.
1815 Transaction date is after the end date of the cardholder.
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 card security code, CVV does not match.
1826 Address information submitted for transaction failed AVS verification.
1828 Card is active.
1829 AVS match.
1830 Card account verification success.
1831 Card not present.
1832 Auth control rules impose a restriction for this merchant ID or merchant category code.
1833 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 exceeds 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 Transaction amount exceeds velocity control set for the transaction.
1842 Account load failed.
1843 Network loads not allowed.
1844 Network advised decline.
1845 Transactions other than ATM and ECommerce not allowed.
1846 ATM transactions not allowed.
1847 ECommerce 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 International transaction blocked due to country or currency.
1865 Insufficient funds in program reserve account.
1866 Invalid card service code.
1868 Quasi cash transaction (processing code 11) not allowed.
1869 KYC is required.
1870 Reloads are disabled for entity.
1871 Push-to-Card disbursement error.
1874 Card expiry date mismatch.