DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

20 minute read

March 4, 2020

Transactions

The /transactions resource represents the electronic messages that carry information used for payment processing. A transaction usually originates when a cardholder 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
Copy section link

Action: GET
Endpoint: /transactions/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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
Required

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 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, 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 cash back 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

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

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

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:

  • 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 cardholder’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
Copy section link

Fields Description

network

object
Conditionally returned

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
Conditionally returned

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
Conditionally returned

Conversion rate when clearing transactions in a currency different than billing currency.

Allowable Values:

Current conversion rate

Note: A value of 0 or 1 indicates no conversion; the currencies are the same.

original_currency_code

string
Conditionally returned

The original three-character ISO 4217 currency type of the transaction.

Allowable Values:

The three-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
Copy section link

{
     "type": "authorization",
     "state": "PENDING",
     "token": "06a8fe88-58b1-4682-a8ad-96eb973e1d74",
     "user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
     "acting_user_token": "99f323d4-298f-4b0c-93b1-19b2d9921eb8",
     "card_token": "02cc766c-24a5-4c3b-adcf-0e5e27b09329",
     "network_reference_id": "0002469298452099894"
     "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"
     }
 }

Is this helpful?

List transactions
Copy section link

Action: GET
Endpoint: /transactions

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

start_date

string
Optional

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: current date minus 30 days (the time of day is not factored in).

end_date

string
Optional

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: current date (the time of day is not factored in).

type

string
Optional

Returns transactions of the specified types.

Allowable Values:

Comma-delimited list of transaction types.

To return all types, leave blank.

Default value: All types (blank)

See Event Types for a list of transaction types.

state

string
Optional

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
Optional

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
Optional

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
Optional

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.

Note
This parameter does not accept business tokens.

card_token

string
Optional

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
Optional

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
Optional

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.

Sample response body
Copy section link

{
     "count": 2,
     "start_index": 0,
     "end_index": 1,
     "is_more": true,
     "data": [
         {
             "type": "gpa.credit.authorization",
             "state": "PENDING",
             "token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
             "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",
             "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"
             }
         }
     ]
 }

Is this helpful?

List related transactions
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

token

string
Required

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
Optional

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: current date minus 30 days (the time of day is not factored in).

end_date

string
Optional

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: current date (the time of day is not factored in).

type

string
Optional

Returns transactions of the specified types.

Allowable Values:

Comma-delimited list of transaction types.

To return all types, leave blank.

Default value: All types (blank)

See Transaction Types for a list of transaction types.

state

string
Optional

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

Sample response body
Copy section link

{
     "count": 1,
     "start_index": 0,
     "end_index": 0,
     "is_more": false,
     "data": [
         {
             "type": "gpa.credit.authorization",
             "state": "PENDING",
             "token": "cd22cff7-2845-4508-a916-cf89fd9edae1",
             "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"
             }
         }
     ]
 }

Is this helpful?

Reverse authorization
Copy section link

Action: POST
Endpoint: /transactions/authorizationreversal

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Required

Identifies the transaction to reverse.

Allowable Values:

Existing transaction token.

Send a GET request to /transactions to retrieve transaction tokens.

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

{
     "type": "authorization.reversal",
     "state": "CLEARED",
     "token": "4114a1dd-bb65-4cf6-924c-bac24e49bf16",
     "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
     }
 }

Is this helpful?

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=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
Copy section link

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

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.

1827

AVS no info.

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

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.

1872

PIN try limit exceeded.

1874

Card expiration date mismatch.

1879

Credit voucher not allowed.

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.