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, either at a physical point of sale or online.

The Marqeta platform provides endpoints for retrieving one or more transactions associated with specific cards, merchants, and account holders (users and businesses). You can also receive information about transactions as they occur by using webhooks.

Note: Use the /transactions endpoint to retrieve smaller data sets (up to one page). For best performance when requesting larger data sets, 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.
user_token Unique identifier of the user who owns the account that funded the transaction.
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).
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).
request_amount Used for clearing/settling transactions to compare to the original authorization amount.
amount Amount of the transaction.
issuer_interchange_amount This is the issuer fee. Only available on authorization.clearing and other completed transaction types.
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. See Merchants for more information.
store Object containing information about the store. See Stores for more information.
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.
offer_orders An array of objects containing information about offer orders, including funding and order balance information. See Orders for more information.
rewards An array of objects containing information about rewards triggered by the transaction.
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.
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.
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 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 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.

Sample response body

{
    "type": "authorization",
    "state": "PENDING",
    "token": "1200",
    "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": "1201",
        "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": 622,
    "created_time": "2018-08-21T17:26:29Z",
    "user_transaction_time": "2018-08-21T17:26:29Z",
    "settlement_date": "2018-08-21T00:00:00Z",
    "request_amount": 10,
    "amount": 10,
    "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": "1201",
            "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": "1200",
            "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": "1201",
                "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",
            "user_transaction_time": "2018-08-21T17:26:29Z",
            "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": "1200",
            "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": "1201",
                "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": 622,
            "created_time": "2018-08-21T17:26:29Z",
            "user_transaction_time": "2018-08-21T17:26:29Z",
            "settlement_date": "2018-08-21T00:00:00Z",
            "request_amount": 10,
            "amount": 10,
            "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
                }
            },
            "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": "1201",
            "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": "1200",
            "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": "1201",
                "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",
            "user_transaction_time": "2018-08-21T17:26:29Z",
            "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": "1201"
}

Sample response body

{
    "type": "authorization.reversal",
    "state": "CLEARED",
    "token": "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": "1200",
    "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": "1203",
        "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",
    "user_transaction_time": "2018-08-21T17:26:29Z",
    "request_amount": 10,
    "amount": 10,
    "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": {
        "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, 1825, 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
1003 Card suspended
1004 Card stolen - pickup
1005 Card lost
1011 Card not found
1012 Cardholder not found
1014 Account not found
1015 Invalid request
1016 Not sufficient funds
1017 Previously reversed
1018 Previously completed
1019 Further activity prevents reversal
1020 Further activity prevents void
1021 Original transaction has been voided
1022 No savings account
1023 No checking account
1802 Missing fields
1803 Extra fields exist
1804 Invalid card number
1806 Card not active
1808 Card not configured
1809 Incorrect PIN
1810 Invalid amount
1811 System error, DB
1812 System error, TXN
1813 Cardholder not active
1814 Cardholder not configured
1815 Cardholder expired
1816 Original not found
1817 Usage limit reached
1818 Configuration error
1819 Invalid terminal
1820 Inactive terminal
1821 Invalid merchant
1822 Duplicate entity
1823 Invalid acquirer
1824 Accounting exception
1825 Invalid CID
1826 AVS decline
1827 AVS no info
1828 Card is active
1829 AVS match
1830 Card account verification success
1831 Card not present
1832 Auth restriction found for given MID or MCC
1833 Cryptographic failure
1834 Transaction amount limit reached
1835 Card product controls prevent transaction
1836 JIT clearing failure
1837 JIT refund failure
1838 International transaction decline
1839 JIT reversal failure
1840 Real time fee group not found
1841 Exceeds max auth amount limit
1842 Account load failed
1843 Network loads not allowed
1844 Issuer timeout advice
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 Transactions not allowed from this country
1865 Insufficient funds in program reserve account
1866 Invalid card service code
1868 Quasi cash TXN not allowed
1869 KYC is required
1870 Reloads are disabled for entity
1871 Push-to-Card disbursement error