/
45 minute read
May 22, 2023

Simulations 2.0 (Beta) — Card Transactions

Note
This feature is currently in beta and subject to change. To learn more about the beta program for this feature, contact your Marqeta representative. For older versions of Simulations, see Simulating Transactions.

The Marqeta platform provides you with a production environment and a sandbox. The main difference between the production and sandbox environments is that your production environment communicates with a payment card network. This communication allows your program’s cards to pay for goods and services by initiating live transactions over the card network.

There are two types of sandbox environments available:

  • Public sandbox: A single-user environment where you can begin building your program and experiment with the Marqeta platform.

  • Private sandbox: A multi-user environment where you can integrate your application with the Marqeta platform.

All funds and transactions are simulated in both types of sandbox environments.

Unlike the production environment, a sandbox does not communicate with a card network, so the cards you create within them cannot be used to conduct real-world transactions. Therefore, you must rely on simulated transactions in order to test all objects you create within a sandbox. The sandbox environments provide a set of endpoints that let you simulate various types of card network transactions, such as authorizations, reversals, and balance inquiries. These endpoints are available only within the sandbox, so the details on this page do not apply to production.

To use the Simulations API for card transactions:

  • Create a card in your sandbox environment.

  • Use the /simulations/cardtransactions/* endpoints to simulate transaction event types. Each endpoint is its own event type.

  • Use the /webhooks endpoint to send optional customer notifications for system events.

To use the Simulations API for direct deposits, see Simulations 2.0 (Beta) — Direct Deposits.

Note
You can use Postman to run requests for card transaction and direct deposit simulations endpoints. This collection of requests has been saved as a YAML file for your convenience. To access the YAML file, see Postman Collection for Simulations 2.0 (Beta).

All card transaction simulations endpoints share the same request/response model, as described below.

Request body

Fields Description

card_token

string
Required

Unique identifier of the card. Useful when a single account holder has multiple cards.

Allowable Values:

36 char max

card_acceptor

object
Required

Contains information about the merchant.

Allowable Values:

A valid card_acceptor object.

card_acceptor.mid

string
Optional

The merchant identifier.

Allowable Values:

2–15 chars

card_acceptor.mcc

string
Optional

Merchant category code (MCC).

Allowable Values:

5 char max

card_acceptor.name

string
Optional

Card acceptor’s name.

Allowable Values:

255 char max

card_acceptor.address

string
Optional

Card acceptor’s address. May be returned if the request uses Transaction Model V1 of the Marqeta Core API. Not returned for V2 requests.

Allowable Values:

255 char max

card_acceptor.city

string
Optional

Card acceptor’s city.

Allowable Values:

255 char max

card_acceptor.state

string
Optional

Two-character state, province, or territorial abbreviation. For a complete list of valid state and province abbreviations, see Valid state, provincial, and territorial abbreviations.

Allowable Values:

2 char max

card_acceptor.postal_code

string
Optional

Card acceptor’s postal code.

Allowable Values:

10 char max

card_acceptor.country_code

string
Optional

Card acceptor’s country code. May be returned if the request uses Transaction Model V2 of the Marqeta Core API. Not returned for V1 requests.

Allowable Values:

40 char max

amount

decimal
Required

Amount of the transaction.

Allowable Values:

0 min

Format: 0.00

cash_back_amount

decimal
Optional

The cashback amount requested.

Allowable Values:

is_preauthorization

boolean
Optional

Indicates if the transaction is a pre-authorization. Set to true to mark the amount as an authorization only.

Allowable Values:

true or false

force_post

boolean
Optional

Set to true to simulate a forced clearing transaction.

NOTE: If you set this field to true, you must also set the original_transaction_token field to an existing transaction token (the transaction does not need to be related).

Allowable Values:

true or false

fees

array of objects
Optional

List of fees associated with the transaction.

This array is returned if it exists in the resource.

Allowable Values:

Existing fees array

fees[].type

string
Optional

The type of fee assessed by the card network.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE, CUR_CONV_ISSUER_FEE, CROSS_BORDER_ISSUER_FEE

fees[].amount

decimal
Optional

The amount of the network fee.

Allowable Values:

Format: 0.00

fees[].credit_debit

string
Optional

Indicates whether the fee is a credit or a debit.

  • C indicates a credit

  • D indicates a debit

Allowable Values:

C, D

card_options

object
Optional

Contains attributes that govern card usage

Allowable Values:

A valid card_options object.

card_options.pin

string
Optional

The PIN for the card.

Allowable Values:

4 char max

card_options.cvv

string
Optional

The CVV2 number for the card.

Allowable Values:

3 chars

card_options.card_present

boolean
Optional

A value of true requires that the card be present for the transaction.

Allowable Values:

true or false

card_options.expiration

string
Optional

The expiration date of the card.

Allowable Values:

4 chars

card_options.billing_address

object
Optional

Used for AVS (address verification system). The address-related fields in this object are verified against known values.

Allowable Values:

A valid billing_address object.

card_options.billing_address.first_name

string
Optional

Cardholder’s first name.

Allowable Values:

To pass AVS, must match the first name on record

card_options.billing_address.last_name

string
Optional

Cardholder’s last name.

Allowable Values:

To pass AVS, must match the last name on record

card_options.billing_address.address

string
Optional

Cardholder’s address.

Allowable Values:

To pass AVS, must match the address on record

card_options.billing_address.zip

string
Optional

Cardholder’s postal code.

Allowable Values:

To pass AVS, must match the postal code on record

pos

object
Optional

Contains information about the point of sale, including details on how the card was presented. May be returned if the request uses Transaction Model V2 of the Marqeta Core API. Not returned for V1 requests.

Allowable Values:

A valid pos object

pos.partial_approval_capable

boolean
Optional

Whether the card acceptor or terminal is capable of partial approvals.

Allowable Values:

true or false

pos.pan_entry_mode

string
Optional

Entry mode used for transaction.

Allowable Values:

MAG_STRIPE, MANUAL, CARD_ON_FILE, CHIP_FALLBACK, BAR_CODE, OCR

preceding_related_transaction_token

string
Optional

Unique identifier of the card. Useful when a single account holder has multiple cards.

Allowable Values:

36 char max

network

string
Optional

Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, DISCOVER, PULSE

subNetwork

string
Optional

Indicates which subnetwork used to complete the transaction.

Allowable Values:

VISANET, VISANETDEBIT, VISAINTERLINK, VISAPLUS, MAESTRO

currency_conversion

object
Optional

Contains information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the origination currency, and the conversion rate.

Returned if the transaction involves currency conversion.

Allowable Values:

A valid currency_conversion object.

currency_conversion.original_amount

decimal
Optional

Amount of the transaction in the currency in which it originated.

Returned if the transaction involves currency conversion.

Allowable Values:

Format: 0.00

currency_conversion.conversion_rate

decimal
Optional

Conversion rate between the origination currency and the settlement currency.

Returned when the transaction currency is different from the origination currency.

Allowable Values:

Current conversion rate.

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

currency_conversion.original_currency_code

string
Optional

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

currency_code

string
Optional

Currency type of the transaction.

Allowable Values:

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWD

account_funding

object
Optional

Information used when funding an account.

Allowable Values:

A valid account_funding object.

account_funding.first_name

string
Required

Account holder’s first name.

Allowable Values:

To pass AVS, must match the first name on record.

account_funding.last_name

string
Optional

Account holder’s last name.

Allowable Values:

To pass AVS, must match the last name on record.

account_funding.receiver_name

string
Optional

Recipient’s name.

Allowable Values:

To pass AVS, must match the name on record.

account_funding.funding_source

string
Required

Describes the source of the funding.

Allowable Values:

CREDIT, DEBIT, PREPAID, DEPOSIT_ACCOUNT, CASH, MOBILE_MONEY_ACCOUNT, NON_VISA_CREDIT

account_funding.receiver_account_type

string
Required

Identifies the account type used for the funding request.

Allowable Values:

OTHER, RTN_BANK_ACCOUNT, IBAN, CARD_ACCOUNT, EMAIL, PHONE_NUMBER, BANK_ACCOUNT_NUMBER_AND_BANK_IDENTIFICATION_CODE, WALLET_ID, SOCIAL_NETWORK_ID

account_funding.transaction_purpose

string
Optional

Identifies the purpose of the transaction.

Allowable Values:

FAMILY_SUPPORT, REGULAR_LABOR_TRANSFERS, TRAVEL_AND_TOURISM, EDUCATION, MEDICAL_TREATMENT, EMERGENCY_NEED, SAVINGS, GIFTS, OTHER, SALARY, CROWD_LENDING, CRYPTO_CURRENCY

account_funding.transaction_type

string
Required

Describes the type of transaction.

Allowable Values:

ACCOUNT_TO_ACCOUNT, PERSON_TO_PERSON, WALLET_TRANSFER, MONEY_TRANSFER_BY_BANK, BUSINESS_TO_BUSINESS, DISBURSEMENT, GOVERNMENT_DISBURSEMENT, GAMBLING_PAYOUT, LOYALTY, MERCHANT_DISBURSEMENT, ONLINE_GAMBLING_PAYOUT, PENSION_DISBURSEMENT, PREPAID_LOADS, CARD_BILL_PAYMENT, BILL_PAYMENT, CASH_CLAIM, CASH_IN, CASH_OUT, MOBILE_AIR_TIME_PAYMENT, MONEY_TRANSFER_BY_MERCHANT, FACE_TO_FACE_MERCHANT_PAYMENT, GOVERNMENT_PAYMENT, PAYMENTS_GOODS_SERVICES, FUNDS_TRANSFER, GENERAL_BUSINESS_TO_BUSINESS_TRANSFER, BUSINESS_TO_BUSINESS_TRANSFER, CASH_DEPOSIT

original_credit

object
Optional

Contains information about an original credit transaction (OCT), which enables the cardholder to receive funds on the specified card from an external source via the card network.

Allowable Values:

Existing original_credit object

original_credit.funding_source

string
Optional

Describes the source of the funding.

Allowable Values:

CREDIT, DEBIT, PREPAID, DEPOSIT_ACCOUNT, CASH, MOBILE_MONEY_ACCOUNT, NON_VISA_CREDIT

original_credit.transaction_type

string
Optional

Describes the type of transaction.

Allowable Values:

ACCOUNT_TO_ACCOUNT, PERSON_TO_PERSON, WALLET_TRANSFER, MONEY_TRANSFER_BY_BANK, BUSINESS_TO_BUSINESS, DISBURSEMENT, GOVERNMENT_DISBURSEMENT, GAMBLING_PAYOUT, LOYALTY, MERCHANT_DISBURSEMENT, ONLINE_GAMBLING_PAYOUT, PENSION_DISBURSEMENT, PREPAID_LOADS, CARD_BILL_PAYMENT, BILL_PAYMENT, CASH_CLAIM, CASH_IN, CASH_OUT, MOBILE_AIR_TIME_PAYMENT, MONEY_TRANSFER_BY_MERCHANT, FACE_TO_FACE_MERCHANT_PAYMENT, GOVERNMENT_PAYMENT, PAYMENTS_GOODS_SERVICES, FUNDS_TRANSFER, GENERAL_BUSINESS_TO_BUSINESS_TRANSFER, BUSINESS_TO_BUSINESS_TRANSFER, CASH_DEPOSIT

original_credit.sender_account_type

string
Optional

The type of account from which the OCT draws funds.

Allowable Values:

OTHER, RTN_BANK_ACCOUNT, IBAN, CARD_ACCOUNT, EMAIL, PHONE_NUMBER, BANK_ACCOUNT_NUMBER_AND_BANK_IDENTIFICATION_CODE, WALLET_ID, SOCIAL_NETWORK_ID

original_credit.sender_name

string
Optional

Full name of the sender.

Allowable Values:

255 char max

original_credit.screening_score

string
Optional

Sanctions screening score to assist with meeting Anti-Money Laundering (AML) obligations.

Higher scores indicate that the sender’s data more closely resembles an entry on the regulatory watchlist.

A value of 999 means that no screening score is available.

Allowable Values:

000-100 or 999

Response body

Fields Description

transaction

object
Conditionally returned

Contains information about the transaction.

Allowable Values:

Existing transaction object

transaction.type

string
Returned

Transaction event type.

For more information about the type field, see Transaction events.

Allowable Values:

account.credit, account.debit, account.funding.auth_plus_capture, account.funding.auth_plus_capture.reversal, account.funding.authorization, account.funding.authorization.clearing, account.funding.authorization.reversal, authorization, authorization.advice, authorization.atm.withdrawal, authorization.cashback, authorization.clearing, authorization.clearing.atm.withdrawal, authorization.clearing.cashback, authorization.clearing.chargeback, authorization.clearing.chargeback.completed, authorization.clearing.chargeback.provisional.credit, authorization.clearing.chargeback.provisional.debit, authorization.clearing.chargeback.reversal, authorization.clearing.chargeback.writeoff, authorization.clearing.quasi.cash, authorization.incremental, authorization.quasi.cash, authorization.reversal, authorization.reversal.issuerexpiration, authorization.standin, balanceinquiry, billpayment, billpayment.clearing, billpayment.reversal, credit.adjustment, debit.adjustment, directdeposit.credit, directdeposit.credit.pending, directdeposit.credit.pending.reversal, directdeposit.credit.reject, directdeposit.credit.reversal, directdeposit.debit, directdeposit.debit.pending, directdeposit.debit.pending.reversal, directdeposit.debit.reject, directdeposit.debit.reversal, dispute.credit, dispute.debit, fee.charge, fee.charge.pending, fee.charge.pending.refund, fee.charge.reversal, funds.expire, gpa.credit, gpa.credit.authorization, gpa.credit.authorization.billpayment, gpa.credit.authorization.billpayment.reversal, gpa.credit.authorization.reversal, gpa.credit.billpayment, gpa.credit.chargeback, gpa.credit.chargeback.reversal, gpa.credit.issueroperator, gpa.credit.networkload, gpa.credit.networkload.reversal, gpa.credit.pending, gpa.credit.pending.reversal, gpa.credit.reversal, gpa.debit, gpa.debit.authorization, gpa.debit.issueroperator, gpa.debit.networkload, gpa.debit.pending, gpa.debit.pending.reversal, gpa.debit.reversal, gpa.grant, msa.credit, msa.credit.chargeback, msa.credit.chargeback.reversal, msa.credit.pending, msa.credit.pending.reversal, msa.credit.reversal, msa.debit, msa.debit.pending, msa.debit.pending.reversal, original.credit.auth_plus_capture, original.credit.auth_plus_capture.reversal, original.credit.authorization, original.credit.authorization.clearing, original.credit.authorization.reversal, pindebit, pindebit.atm.withdrawal, pindebit.authorization, pindebit.authorization.clearing, pindebit.authorization.reversal, pindebit.authorization.reversal.issuerexpiration, pindebit.balanceinquiry, pindebit.cashback, pindebit.chargeback, pindebit.chargeback.completed, pindebit.chargeback.provisional.credit, pindebit.chargeback.provisional.debit, pindebit.chargeback.reversal, pindebit.chargeback.writeoff, pindebit.credit.adjustment, pindebit.quasi.cash, pindebit.quasicash, pindebit.refund, pindebit.refund.reversal, pindebit.reversal, pindebit.transfer, programreserve.credit, programreserve.debit, pushtocard.debit, pushtocard.reversal, refund, refund.authorization, refund.authorization.advice, refund.authorization.clearing, refund.authorization.reversal, reward.earn, token.activation-request, token.advice, transfer.fee, transfer.peer, transfer.program, unknown

transaction.state

string
Returned

Current state of the transaction.

For more information about the state field, see The transaction lifecycle.

Allowable Values:

CLEARED, COMPLETION, DECLINED, ERROR, PENDING

transaction.token

string
Returned

Unique identifier of the transaction, formatted as a UUID.

NOTE: For subsequent related transactions, this token value appears as the preceding_related_transaction_token.

Allowable Values:

1–36 chars

transaction.user_token

string
Conditionally returned

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 to complete the transaction moves to another user.

Allowable Values:

36 char max

transaction.card_token

string
Conditionally returned

Unique identifier of the card. Useful when a single account holder has multiple cards.

Allowable Values:

36 char max

transaction.response

object
Conditionally returned

Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

Existing response object

transaction.response.code

string
Returned

Four-digit code corresponding with the outcome of the attempted transaction type.

  • 0000 – passed

  • 0001 – did not pass

Allowable Values:

Four-digit code

transaction.response.memo

string
Returned

Information on the outcome of the attempted transaction type.

Allowable Values:

255 char max

transaction.response.additional_information

string
Conditionally returned

Information about the relevant velocity control for the transaction, if applicable.

Allowable Values:

The additional_information field returns a string in the following format: <Velocity control name>, cumulative transaction amount is <X>, where X is the cumulative transaction amount value calculated by Marqeta. For example: 500 max spend per day, cumulative transaction amount is 750.

transaction.created_time

datetime
Conditionally returned

Date and time when the Marqeta platform created the transaction entry, in UTC format. For example, when Marqeta processed the clearing record for a refund.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

transaction.user_transaction_time

datetime
Conditionally returned

Date and time when the user initiated the transaction, in UTC. For example, when a merchant performed the original authorization for a refund.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

transaction.settlement_date

datetime
Conditionally returned

Date and time when funds were moved for a transaction, in UTC. For example, in the case of a refund, when funds were credited to the cardholder.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

transaction.amount

decimal
Returned

Amount of the transaction.

Allowable Values:

Format: 0.00

transaction.amount_to_be_released

decimal
Conditionally returned

Amount to released following a financial advice.

Allowable Values:

Format: 0.00

transaction.cash_back_amount

decimal
Conditionally returned

The cashback amount requested.

Allowable Values:

Format: 0.00

transaction.request_amount

decimal
Conditionally returned

Merchant-requested amount, including any fees. This includes amount and cashback amount.

Allowable Values:

Format: 0.00

transaction.gpa

object
Conditionally returned

Contains information about the GPA balances and pending credits.

Allowable Values:

available_balance, balances, cached_balance, credit_balance, currency_code, impacted_amount, last_updated_time, ledger_balance, pending_credits

transaction.gpa.ledger_balance

decimal
Conditionally returned

When using standard funding: The funds that are available to spend immediately, including funds from any authorized transactions that have not yet cleared. When using Just-in-Time (JIT) Funding: Authorized funds that are currently on hold, but not yet cleared.

Allowable Values:

Format: 0.00

transaction.gpa.available_balance

decimal
Conditionally returned

Ledger balance minus any authorized transactions that have not yet cleared. Also known as the cardholder’s purchasing power. When using JIT Funding, this balance is usually equal to $0.00.

Allowable Values:

Format: 0.00

transaction.gpa.impacted_amount

decimal
Conditionally returned

Balance change based on the amount of the transaction.

Allowable Values:

Format: 0.00

transaction.currency_code

string
Conditionally returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

transaction.currency_conversion

object
Conditionally returned

Contains information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the origination currency, and the conversion rate.

Returned if the transaction involves currency conversion.

Allowable Values:

A valid currency_conversion object.

transaction.currency_conversion.original_amount

decimal
Conditionally returned

Amount of the transaction in the currency in which it originated.

Returned if the transaction involves currency conversion.

Allowable Values:

Format: 0.00

transaction.currency_conversion.conversion_rate

decimal
Conditionally returned

Conversion rate between the origination currency and the settlement currency.

Returned when the transaction currency is different from the origination currency.

Allowable Values:

Current conversion rate.

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

transaction.currency_conversion.original_currency_code

string
Conditionally returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

transaction.preceding_related_transaction_token

string
Conditionally returned

Returned for final transaction types.

Unique identifier of the preceding related transaction. Useful for identifying the transaction that preceded the current one. For example, authorization, a temporary transaction type, precedes and is completed by authorization.clearing, a final transaction type.

In this case, the authorization token is returned with this field. See Transaction events for details on which transaction types are temporary or final.

Allowable Values:

UUID

transaction.network

string
Conditionally returned

Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, PULSE, DISCOVER

transaction.subnetwork

string
Conditionally returned

Indicates which subnetwork used to complete the transaction.

Allowable Values:

VISANET, VISANETDEBIT, VISAINTERLINK, VISAPLUS, MAESTRO

transaction.acquirer_fee_amount

decimal
Conditionally returned

Indicates the amount of the acquirer fee. Account holders are sometimes charged an acquirer fee for card use at ATMs, fuel dispensers, and so on.

Allowable Values:

Format: 0.00

transaction.fees

array of objects
Conditionally returned

List of fees associated with the transaction.

This array is returned if it exists in the resource.

Allowable Values:

Array of existing fees objects

transaction.fees[].type

string
Conditionally returned

The type of fee assessed by the card network.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE, CUR_CONV_ISSUER_FEE, CROSS_BORDER_ISSUER_FEE

transaction.fees[].amount

decimal
Conditionally returned

The amount of the network fee.

Allowable Values:

Format: 0.00

transaction.fees[].credit_debit

string
Conditionally returned

Indicates whether the fee is a credit or a debit.

  • C indicates a credit

  • D indicates a debit

Allowable Values:

C, D

transaction.fraud

object
Conditionally returned

Contains one or more fraud determinations by the card network that apply to either the transaction or the cardholder’s account.

Allowable Values:

issuer_processor, network_fraud_view, network_account_intelligence_score

transaction.fraud.network

object
Conditionally returned

Contains network-provided information about fraud determinations.

Allowable Values:

account_risk_score, account_risk_score_reason_code, transaction_risk_score, transaction_risk_score_reason_code, transaction_risk_score_reason_description

transaction.fraud.network.transaction_risk_score

integer
Conditionally returned

Network-provided risk score for the transaction. A higher score indicates higher risk. Useful for making authorization decisions.

Allowable Values:

Mastercard: 0-999

Visa: 1-99

transaction.fraud.network.transaction_risk_score_reason_code

string
Conditionally returned

(Mastercard only) Unique code that describes the main driver of the transaction_risk_score.

Allowable Values:

1-29

transaction.fraud.network.transaction_risk_score_reason_description

string
Conditionally returned

(Mastercard only) Description of the transaction_risk_score_reason_code.

Allowable Values:

255 char max

transaction.fraud.network.account_risk_score

string
Conditionally returned

(Visa only) Account holder risk condition code evaluated by the card network. A higher score indicates a greater likelihood that the card number is compromised.

Allowable Values:

1-9

transaction.fraud.network.account_risk_score_reason_code

string
Conditionally returned

(Visa only) Unique code that describes the main driver of the account_risk_score.

Allowable Values:

255 char max

transaction.card_acceptor

object
Conditionally returned

Contains information about the merchant.

Allowable Values:

A valid card_acceptor object.

transaction.card_acceptor.mid

string
Conditionally returned

The merchant identifier.

Allowable Values:

2–15 chars

transaction.card_acceptor.mcc

string
Conditionally returned

Merchant category code (MCC).

Allowable Values:

5 char max

transaction.card_acceptor.name

string
Conditionally returned

Card acceptor’s name.

Allowable Values:

255 char max

transaction.card_acceptor.address

string
Conditionally returned

Card acceptor’s address. May be returned if the request uses Transaction Model V1 of the Marqeta Core API. Not returned for V2 requests.

Allowable Values:

255 char max

transaction.card_acceptor.city

string
Conditionally returned

Card acceptor’s city.

Allowable Values:

255 char max

transaction.card_acceptor.state

string
Conditionally returned

Two-character state, province, or territorial abbreviation. For a complete list of valid state and province abbreviations, see Valid state, provincial, and territorial abbreviations.

Allowable Values:

2 char max

transaction.card_acceptor.postal_code

string
Conditionally returned

Card acceptor’s postal code.

Allowable Values:

10 char max

transaction.card_acceptor.country_code

string
Conditionally returned

Card acceptor’s country code. May be returned if the request uses Transaction Model V2 of the Marqeta Core API. Not returned for V1 requests.

Allowable Values:

40 char max

transaction.account_funding

object
Conditionally returned

Information used when funding an account.

Allowable Values:

A valid account_funding object.

transaction.account_funding.first_name

string
Returned

Account holder’s first name.

Allowable Values:

To pass AVS, must match the first name on record.

transaction.account_funding.last_name

string
Conditionally returned

Account holder’s last name.

Allowable Values:

To pass AVS, must match the last name on record.

transaction.account_funding.receiver_name

string
Conditionally returned

Recipient’s name.

Allowable Values:

To pass AVS, must match the name on record.

transaction.account_funding.funding_source

string
Returned

Describes the source of the funding.

Allowable Values:

CREDIT, DEBIT, PREPAID, DEPOSIT_ACCOUNT, CASH, MOBILE_MONEY_ACCOUNT, NON_VISA_CREDIT

transaction.account_funding.receiver_account_type

string
Returned

Identifies the account type used for the funding request.

Allowable Values:

OTHER, RTN_BANK_ACCOUNT, IBAN, CARD_ACCOUNT, EMAIL, PHONE_NUMBER, BANK_ACCOUNT_NUMBER_AND_BANK_IDENTIFICATION_CODE, WALLET_ID, SOCIAL_NETWORK_ID

transaction.account_funding.transaction_purpose

string
Conditionally returned

Identifies the purpose of the transaction.

Allowable Values:

FAMILY_SUPPORT, REGULAR_LABOR_TRANSFERS, TRAVEL_AND_TOURISM, EDUCATION, MEDICAL_TREATMENT, EMERGENCY_NEED, SAVINGS, GIFTS, OTHER, SALARY, CROWD_LENDING, CRYPTO_CURRENCY

transaction.account_funding.transaction_type

string
Returned

Describes the type of transaction.

Allowable Values:

ACCOUNT_TO_ACCOUNT, PERSON_TO_PERSON, WALLET_TRANSFER, MONEY_TRANSFER_BY_BANK, BUSINESS_TO_BUSINESS, DISBURSEMENT, GOVERNMENT_DISBURSEMENT, GAMBLING_PAYOUT, LOYALTY, MERCHANT_DISBURSEMENT, ONLINE_GAMBLING_PAYOUT, PENSION_DISBURSEMENT, PREPAID_LOADS, CARD_BILL_PAYMENT, BILL_PAYMENT, CASH_CLAIM, CASH_IN, CASH_OUT, MOBILE_AIR_TIME_PAYMENT, MONEY_TRANSFER_BY_MERCHANT, FACE_TO_FACE_MERCHANT_PAYMENT, GOVERNMENT_PAYMENT, PAYMENTS_GOODS_SERVICES, FUNDS_TRANSFER, GENERAL_BUSINESS_TO_BUSINESS_TRANSFER, BUSINESS_TO_BUSINESS_TRANSFER, CASH_DEPOSIT

transaction.gpa_order

object
Conditionally returned

Contains information about a GPA order, including fees, funding sources, and addresses. See GPA Orders for more information.

Allowable Values:

Existing gpa_order object

transaction.gpa_order.amount

decimal
Returned

Amount funded.

Allowable Values:

Format: 0.00

transaction.gpa_order.created_time

datetime
Returned

Date and time when the GPA order was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

transaction.gpa_order.currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

transaction.gpa_order.fees

array of objects
Conditionally returned

List of fees associated with the transaction.

This array is returned if it exists in the resource.

Allowable Values:

Array of existing fees objects

transaction.gpa_order.fees[].fee

object
Returned

Contains details about the fee.

Allowable Values:

active, amount, created_time, currency_code, last_modified_time, name, real_time_assessment, tags, token

transaction.gpa_order.fees[].fee.active

boolean
Returned

Indicates whether the fee is active.

Allowable Values:

true or false

transaction.gpa_order.fees[].fee.amount

decimal
Returned

Amount of the fee.

Allowable Values:

Format: 0.00

transaction.gpa_order.fees[].fee.created_time

datetime
Returned

Date and time when the fees object was created, in UTC.

Allowable Values:

yyyy-MM-ddTHH:mm:ssZ

transaction.gpa_order.fees[].fee.currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

transaction.gpa_order.fees[].fee.last_modified_time

datetime
Returned

Date and time when the GPA order was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

transaction.gpa_order.fees[].fee.name

string
Returned

Name of the fee.

Allowable Values:

50 char max

transaction.gpa_order.fees[].fee.real_time_assessment

object
Conditionally returned

Controls the assessment of real-time fees.

Allowable Values:

domestic_enabled, international_enabled, transaction_type

transaction.gpa_order.fees[].fee.real_time_assessment.domestic_enabled

boolean
Conditionally returned

Enables fee assessments where the origin of the transaction acquirer is inside the US.

Allowable Values:

true, false

transaction.gpa_order.fees[].fee.real_time_assessment.international_enabled

boolean
Conditionally returned

Enables fee assessments where the origin of the transaction acquirer is outside the US.

Allowable Values:

true, false

transaction.gpa_order.fees[].fee.real_time_assessment.transaction_type

string
Conditionally returned

Indicates the type of transactions on which the fee is assessed.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

transaction.gpa_order.fees[].fee.tags

string
Conditionally returned

Descriptive metadata about the fee.

Allowable Values:

255 char max

transaction.gpa_order.fees[].fee.token

string
Returned

Unique identifier of the fees object.

Allowable Values:

Existing fees object token

transaction.gpa_order.fees[].memo

string
Conditionally returned

Additional text that describes the fee transfer.

Allowable Values:

1–99 chars

transaction.gpa_order.fees[].tags

string
Conditionally returned

Descriptive metadata about the fee.

Allowable Values:

255 char max

transaction.gpa_order.fees[].token

string
Returned

Unique identifier of the fee.

Allowable Values:

1–36 chars

transaction.gpa_order.fees[].transaction_token

string
Returned

Unique identifier of the fee transaction.

Allowable Values:

36 char max

transaction.gpa_order.funding

object
Returned

Contains funding information for the transaction, including funding amount, type, and time.

Allowable Values:

amount, gateway_log, source, source_address

transaction.gpa_order.funding.amount

decimal
Conditionally returned

Amount of funds loaded into the GPA.

Allowable Values:

Format: 0.00

transaction.gpa_order.funding.gateway_log

object
Conditionally returned

Contains information from the JIT Funding gateway in response to a funding request.

Allowable Values:

duration, message, order_number, response, timed_out, transaction_id

transaction.gpa_order.funding.gateway_log.duration

integer
Conditionally returned

Length of time in milliseconds that the gateway took to respond to a funding request.

Allowable Values:

Any integer

transaction.gpa_order.funding.gateway_log.message

string
Returned

Message about the status of the funding request. Useful for determining whether it was approved and completed successfully, declined by the gateway, or timed out.

Allowable Values:

Approved or completed successfully, Declined by gateway, Operation timeout

transaction.gpa_order.funding.gateway_log.order_number

string
Returned

Customer order number, same value as transaction.token.

Allowable Values:

Existing transaction.token value

transaction.gpa_order.funding.gateway_log.timed_out

boolean
Conditionally returned

Whether the gateway sent a response (true) or timed out (false).

Allowable Values:

true, false

transaction.gpa_order.funding.gateway_log.transaction_id

string
Returned

Customer-defined identifier for the transaction.

Allowable Values:

255 char max

transaction.gpa_order.funding.source

object
Returned

Contains funding source information for the transaction, including the funding type and time.

Allowable Values:

active, created_time, is_default_account, last_modified_time, token, type

transaction.gpa_order.funding.source.active

boolean
Returned

Whether the funding source is active.

Allowable Values:

true, false

transaction.gpa_order.funding.source.created_time

datetime
Returned

Date and time when the funding source was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

transaction.gpa_order.funding.source.is_default_account

boolean
Returned

Whether the GPA order unload’s funding source is the default funding account.

Allowable Values:

true, false

transaction.gpa_order.funding.source.last_modified_time

datetime
Returned

Date and time when the funding source was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

transaction.gpa_order.funding.source.token

string
Returned

Unique identifier of the funding source.

Allowable Values:

Format: UUID

transaction.gpa_order.funding.source.type

string
Returned

Funding type of the funding source.

Allowable Values:

ach, paymentcard

transaction.gpa_order.funding.source_address

object
Conditionally returned

Contains information about the billing address of the funding source.

Allowable Values:

active, address_1, address_2, business_token, city, country, created_time, first_name, is_default_address, last_modified_time, last_name, phone, postal_code, state, token, user_token, zip

transaction.gpa_order.funding.source_address.active

boolean
Conditionally returned

Whether the address is active.

Allowable Values:

true, false

transaction.gpa_order.funding.source_address.address_1

string
Returned

Street address of the funding source.

Allowable Values:

255 char max

transaction.gpa_order.funding.source_address.address_2

string
Conditionally returned

Additional address information for the funding source.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

transaction.gpa_order.funding.source_address.business_token

string
Conditionally returned

Unique identifier of the business account holder associated with the address.

This field is returned if it exists in the resource. It is required if 'user_token' is not specified.

Allowable Values:

1–36 chars

transaction.gpa_order.funding.source_address.city

string
Returned

City of the funding source.

Allowable Values:

40 char max

transaction.gpa_order.funding.source_address.country

string
Returned

Country of the funding source.

Allowable Values:

1–40 chars

transaction.gpa_order.funding.source_address.created_time

datetime
Returned

Date and time when the address was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

transaction.gpa_order.funding.source_address.first_name

string
Returned

First name of the account holder associated with the funding source.

Allowable Values:

40 char max

transaction.gpa_order.funding.source_address.is_default_address

boolean
Conditionally returned

Whether this address is the default address used by the funding source.

Allowable Values:

true, false

transaction.gpa_order.funding.source_address.last_modified_time

datetime
Returned

Date and time when the address was last modified, in UTC.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

transaction.gpa_order.funding.source_address.last_name

string
Returned

Last name of the account holder associated with the funding source.

Allowable Values:

40 char max

transaction.gpa_order.funding.source_address.phone

string
Conditionally returned

Phone number of the funding source.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

transaction.gpa_order.funding.source_address.postal_code

string
Returned

Postal code of the funding source.

Allowable Values:

10 char max

transaction.gpa_order.funding.source_address.state

string
Returned

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

transaction.gpa_order.funding.source_address.token

string
Returned

Unique identifier of the funding_source_address object.

Allowable Values:

1–36 chars

transaction.gpa_order.funding.source_address.user_token

string
Conditionally returned

Unique identifier of the user account holder associated with the address.

This field is returned if it exists in the resource. It is required if 'business_token' is not specified.

Allowable Values:

1–36 chars

transaction.gpa_order.funding.source_address.zip

string
Returned

United States ZIP code of the funding source.

Allowable Values:

10 char max

transaction.gpa_order.funding_source_address_token

string
Conditionally returned

Unique identifier of the funding source address to use for this order.

Allowable Values:

Existing funding_source_address token

transaction.gpa_order.funding_source_token

string
Returned

Unique identifier of the funding source to use for this order.

Allowable Values:

Existing funding_source_address token

transaction.gpa_order.gateway_message

string
Conditionally returned

Message about the status of the funding request. Useful for determining whether it was approved and completed successfully, declined by the gateway, or timed out.

This field is returned if it exists in the resource.

Allowable Values:

Approved or completed successfully, Declined by gateway, Operation timeout

transaction.gpa_order.gateway_token

integer
Conditionally returned

Unique identifier of the funding source to use for this order.

Allowable Values:

Existing gateway_token

transaction.gpa_order.jit_funding

object
Conditionally returned

Contains information about the JIT Funding load event, in which funds are loaded into an account.

Allowable Values:

acting_user_token, address_verification, amount, balances, business_token, decline_reason, incremental_authorization_jit_funding_tokens, memo, method, original_jit_funding_token, tags, token, user_token

transaction.gpa_order.jit_funding.amount

decimal
Returned

Requested amount of funding.

Allowable Values:

0 min

transaction.gpa_order.jit_funding.balances

object
Conditionally returned

Contains the GPA’s balance details.

Allowable Values:

Existing balances object

transaction.gpa_order.jit_funding.business_token

string
Conditionally returned

Holder of the business account that was funded.

Allowable Values:

36 char max

transaction.gpa_order.jit_funding.decline_reason

string
Conditionally returned

Reason why the transaction was declined.

Allowable Values:

INVALID_AMOUNT, INSUFFICIENT_FUNDS, TRANSACTION_NOT_PERMITTED, SUSPECTED_FRAUD, AMOUNT_LIMIT_EXCEEDED, TRANSACTION_COUNT_LIMIT_EXCEEDED, DUPLICATE_TRANSACTION, INVALID_MERCHANT, INVALID_CARD, NO_CREDIT_ACCOUNT, EXPIRED_CARD, NO_CHECKING_ACCOUNT, NO_SAVINGS_ACCOUNT, STOP_PAYMENT, REVOCATION_AUTHORIZATION_ORDER, REVOCATION_ALL_AUTHORIZATION_ORDER, SOFT_DECLINE_AUTHENTICATION_REQUIRED, CLOSED_ACCOUNT, SOFT_DECLINE_PIN_REQUIRED, CARD_NOT_ACTIVE, CARDHOLDER_NOT_ACTIVE

transaction.gpa_order.jit_funding.incremental_authorization_jit_funding_tokens

array of strings
Conditionally returned

Array of tokens referencing the JIT Funding tokens of all previous associated incremental authorization JIT Funding requests. Useful for ascertaining the final transaction amount when the original amount was incremented.

Allowable Values:

Existing incremental authorization JIT Funding tokens

transaction.gpa_order.jit_funding.memo

string
Conditionally returned

Additional information that describes the JIT Funding transaction.

Allowable Values:

99 char max

transaction.gpa_order.jit_funding.method

string
Returned

JIT Funding response type. See The jit_funding object for the purpose, funding event type, and description of each method.

Allowable Values:

pgfs.authorization, pgfs.balanceinquiry, pgfs.authorization.incremental, pgfs.authorization.capture, pgfs.authorization.reversal, pgfs.auth_plus_capture, pgfs.refund, pgfs.force_capture, pgfs.authorization.capture.chargeback, pgfs.authorization.capture.chargeback.reversal, pgfs.pindebit.chargeback, pgfs.pindebit.chargeback.reversal, pgfs.dispute.credit, pgfs.dispute.debit, pgfs.directdeposit.credit, pgfs.directdeposit.debit, pgfs.directdeposit.credit.reversal, pgfs.directdeposit.debit.reversal, pgfs.adjustment.credit, pgfs.adjustment.debit, pgfs.auth_plus_capture.standin, pgfs.authorization.standin, pgfs.network.load, pgfs.original.credit.authorization, pgfs.original.credit.auth_plus_capture, pgfs.refund.authorization, pgfs.refund.authorization.reversalpgfs.billpayment, pgfs.billpayment.capture, pgfs.billpayment.reversal, pgfs.authorization.account_verification

transaction.gpa_order.jit_funding.original_jit_funding_token

string
Conditionally returned

Unique identifier of the first associated JIT Funding message. Useful for correlating related JIT Funding messages (that is, those associated with the same GPA order). Not included in the first of any set of related messages.

Allowable Values:

36 char max

transaction.gpa_order.jit_funding.tags

string
Conditionally returned

Customer-defined tags related to the JIT Funding transaction.

Allowable Values:

255 char max

transaction.gpa_order.jit_funding.token

string
Returned

Existing JIT Funding token matching the funding.gateway_log.transaction_id field of the associated GPA order. Note that the transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.

Allowable Values:

36 char max

transaction.gpa_order.jit_funding.user_token

string
Returned

Holder of the user account that was funded.

Allowable Values:

36 char max

transaction.gpa_order.last_modified_time

datetime
Returned

Date and time when the fees object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

transaction.gpa_order.memo

string
Conditionally returned

Additional descriptive text.

This field is returned if it exists in the resource.

Allowable Values:

99 char max

transaction.gpa_order.response

object
Returned

Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

Existing response object

transaction.gpa_order.response.code

string
Returned

Four-digit code corresponding with the outcome of the attempted transaction type.

  • 0000 – passed

  • 0001 – did not pass

Allowable Values:

Four-digit code

transaction.gpa_order.response.memo

string
Returned

Information on the outcome of the attempted transaction type.

Allowable Values:

255 char max

transaction.gpa_order.response.additional_information

string
Conditionally returned

Information about the relevant velocity control for the transaction, if applicable.

Allowable Values:

The additional_information field returns a string in the following format: <Velocity control name>, cumulative transaction amount is <X>, where X is the cumulative transaction amount value calculated by Marqeta. For example: 500 max spend per day, cumulative transaction amount is 750.

transaction.gpa_order.state

string
Returned

Current status of the funding transaction.

Allowable Values:

PENDING, CLEARED, COMPLETION, DECLINED, ERROR, ALL

transaction.gpa_order.tags

string
Conditionally returned

Comma-delimited list of tags describing the order.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

transaction.gpa_order.token

string
Returned

Unique identifier of the GPA order.

Allowable Values:

36 char max

transaction.gpa_order.transaction_token

string
Returned

Unique identifier of the transaction being funded.

Allowable Values:

Format: UUID

transaction.gpa_order.user_token

string
Conditionally returned

Unique identifier of the user resource.

This field is returned if it exists in the resource.

Allowable Values:

Existing user resource token

transaction.original_credit

object
Conditionally returned

Contains information about an original credit transaction (OCT), which enables the cardholder to receive funds on the specified card from an external source via the card network.

Allowable Values:

Existing original_credit object

transaction.original_credit.funding_source

string
Conditionally returned

Describes the source of the funding.

Allowable Values:

CREDIT, DEBIT, PREPAID, DEPOSIT_ACCOUNT, CASH, MOBILE_MONEY_ACCOUNT, NON_VISA_CREDIT

transaction.original_credit.transaction_type

string
Conditionally returned

Describes the type of transaction.

Allowable Values:

ACCOUNT_TO_ACCOUNT, PERSON_TO_PERSON, WALLET_TRANSFER, MONEY_TRANSFER_BY_BANK, BUSINESS_TO_BUSINESS, DISBURSEMENT, GOVERNMENT_DISBURSEMENT, GAMBLING_PAYOUT, LOYALTY, MERCHANT_DISBURSEMENT, ONLINE_GAMBLING_PAYOUT, PENSION_DISBURSEMENT, PREPAID_LOADS, CARD_BILL_PAYMENT, BILL_PAYMENT, CASH_CLAIM, CASH_IN, CASH_OUT, MOBILE_AIR_TIME_PAYMENT, MONEY_TRANSFER_BY_MERCHANT, FACE_TO_FACE_MERCHANT_PAYMENT, GOVERNMENT_PAYMENT, PAYMENTS_GOODS_SERVICES, FUNDS_TRANSFER, GENERAL_BUSINESS_TO_BUSINESS_TRANSFER, BUSINESS_TO_BUSINESS_TRANSFER, CASH_DEPOSIT

transaction.original_credit.sender_account_type

string
Conditionally returned

The type of account from which the OCT draws funds.

Allowable Values:

OTHER, RTN_BANK_ACCOUNT, IBAN, CARD_ACCOUNT, EMAIL, PHONE_NUMBER, BANK_ACCOUNT_NUMBER_AND_BANK_IDENTIFICATION_CODE, WALLET_ID, SOCIAL_NETWORK_ID

transaction.original_credit.sender_name

string
Conditionally returned

Full name of the sender.

Allowable Values:

255 char max

transaction.original_credit.screening_score

string
Conditionally returned

Sanctions screening score to assist with meeting Anti-Money Laundering (AML) obligations.

Higher scores indicate that the sender’s data more closely resembles an entry on the regulatory watchlist.

A value of 999 means that no screening score is available.

Allowable Values:

000-100 or 999

Simulate authorization

Action: POST
Endpoint: /simulations/cardtransactions/authorization

Authorization is the process of confirming whether a card is valid, business rules are met, and funds are sufficient, and then placing a temporary hold on those funds. Use this endpoint to simulate an authorization type transaction by including the card_token and other authorization details in your request.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate authorization advice

Action: POST
Endpoint: /simulations/cardtransactions/authorization.advice

Authorization advice allows an amount to be decreased after the authorization. This endpoint allows you to simulate post-swipe adjustments. Simulate an authorization.advice transaction by including the preceding_related_transaction_token and other authorization details in your request.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/authorization.clearing

Clearing is the process of finalizing the hold on funds and posting the transaction on the cardholder’s account. This process is triggered by the merchant’s capture request. This endpoint simulates an authorization.clearing type transaction by including the preceding_related_transaction_token and amount in your request.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate authorization reversal

Action: POST
Endpoint: /simulations/cardtransactions/authorization.reversal

A reversal releases the hold that was placed on account funds by an authorization, thus returning the funds to the account. This endpoint simulates an authorization.reversal type transaction by including the original_transaction_token and amount in your request.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate incremental authorization

Action: POST
Endpoint: /simulations/cardtransactions/authorization.incremental

Use this endpoint to simulate incremental authorization transactions. An incremental authorization is a request to add an additional dollar amount to an ongoing prior authorization. This type of transaction enables you to increase the final amount authorized as conditions change or additional charges accrue. A common use case is adding the gratuity (an incremental authorization) to the original total (a prior authorization) of a restaurant bill.

For this use case, you use two endpoints: one to create the authorization, and another to increment it.

  • Create the authorization using the /cardtransactions/authorization endpoint:
    Action: POST
    Endpoint: /simulations/cardtransactions/authorization

  • Increment the authorization using the /cardtransactions/authorization.incremental endpoint:
    Action: POST
    Endpoint: /simulations/cardtransactions/authorization.incremental

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate authorization cash back

Action: POST
Endpoint: /simulations/cardtransactions/authorization.cashback

Use this endpoint to simulate authorization.cashback transactions, which covers authorization for cash back requested at a point-of-sale terminal. This simulation can be used to test dual-message cash back transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate ATM withdrawal authorization

Action: POST
Endpoint: /simulations/cardtransactions/authorization.atm.withdrawal

Use this endpoint to simulate authorization.atm.withdrawal transactions. In the EU, this includes authorization for withdrawing cash at an ATM. In the US, this event indicates that the cardholder got cash from a bank teller rather than an ATM. This simulation can be used to test dual-message ATM withdrawal transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate ATM withdrawal authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/authorization.clearing.atm.withdrawal

Use this endpoint to simulate authorization.clearing.atm.withdrawal transactions, which completes an authorization for withdrawing cash at an ATM. This simulation can be used to test dual-message ATM withdrawal transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate quasi-cash authorization

Action: POST
Endpoint: /simulations/cardtransactions/authorization.quasi.cash

Use this endpoint to simulate authorization.quasi.cash transactions. This is for authorization at a point-of-sale terminal for items equivalent to cash, such as traveler’s checks, money orders, foreign currency, or gaming chips. This simulation can be used to test dual-message quasi-cash transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate quasi-cash authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/authorization.clearing.quasi.cash

Use this endpoint to simulate authorization.clearing.quasi.cash transactions, which completes an authorization at a point-of-sale terminal for items equivalent to cash, such as traveler’s checks, money orders, foreign currency, or gaming chips. This simulation can be used to test dual-message quasi-cash transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate AFT authorization

Action: POST
Endpoint: /simulations/cardtransactions/account.funding.authorization

Use this endpoint to simulate Account Funding Transactions (AFTs) using account.funding.authorization.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate AFT authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/account.funding.authorization.clearing

Use this endpoint to simulate account.funding.authorization.clearing transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate AFT authorization reversal

Action: POST
Endpoint: /simulations/cardtransactions/account.funding.authorization.reversal

Use this endpoint to simulate account.funding.authorization.reversal transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate AFT authorization and capture

Action: POST
Endpoint: /simulations/cardtransactions/account.funding.auth_plus_capture

Use this endpoint to simulate account.funding.auth_plus_capture transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate AFT authorization and capture reversal

Action: POST
Endpoint: /simulations/cardtransactions/account.funding.auth_plus_capture.reversal

Use this endpoint to simulate account.funding.auth_plus_capture.reversal transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate refund

Action: POST
Endpoint: /simulations/cardtransactions/refund

Use this endpoint to simulate an offline refund. Refunds are not associated with a token, so a preceding_related_transaction_token is not needed.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate refund authorization

Action: POST
Endpoint: /simulations/cardtransactions/refund.authorization

Online refund refers to the refund.authorization messages that Visa and Mastercard merchants can send to card issuers. These refund authorizations allow merchants to notify customers of a pending refund and give card issuers the opportunity to decline a refund. Like purchase authorizations, refund authorizations are eventually cleared or completed by a refund.authorization.clearing event. That refund authorization clearing is automatically accepted and processed by the Marqeta platform, regardless of your funding model.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate refund authorization reversal

Action: POST
Endpoint: /simulations/cardtransactions/refund.authorization.reversal

Use this endpoint to reject refund.authorization transactions for online refunds.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate refund authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/refund.authorization.clearing

Use this endpoint to simulate online refund clearing.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit

Action: POST
Endpoint: /simulations/cardtransactions/pindebit

Use this endpoint to simulate transactions using network debit rails.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit authorization

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.authorization

Use this endpoint to simulate PIN-debit authorization transactions. The typical use case for dual-message PIN-debit transactions is automated fuel dispenser transactions. The pump sends an initial authorization message to the card issuer. When fueling completes, a clearing message is sent with the final amount.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.authorization.clearing

Use this endpoint to clear pindebit.authorization transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit authorization reversal

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.authorization.reversal

Use this endpoint to reverse pindebit.authorization transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit cash back

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.cashback

Simulate a PIN-debit transaction for cash back requested at a point-of-sale terminal.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit refund

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.refund

Use this endpoint to simulate a PIN-debit transaction refund.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit ATM withdrawal

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.atm.withdrawal

Use this endpoint to simulate a cash withdrawal at an ATM.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit balance inquiry

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.balanceinquiry

Use this endpoint to simulate a balance inquiry via the card network. This is a non-financial transaction.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate PIN-debit quasi-cash

Action: POST
Endpoint: /simulations/cardtransactions/pindebit.quasi.cash

Use this endpoint to simulate pindebit.quasi.cash transactions. This PIN-debit transaction occurs at a point-of-sale terminal for items equivalent to cash, such as traveler’s checks, money orders, foreign currency, or gaming chips. This simulation can be used to test single-message cash back transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate OCT authorization

Action: POST
Endpoint: /simulations/cardtransactions/original.credit.authorization

Use this endpoint to simulate original.credit.authorization transactions. This is for original credit transaction (OCT) authorization for disbursing funds to a credit card. This simulation can be used to test dual-message OCT transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate OCT authorization clearing

Action: POST
Endpoint: /simulations/cardtransactions/original.credit.authorization.clearing

Use this endpoint to simulate original.credit.authorization.clearing transactions, which completes an original credit transaction (OCT) authorization. This simulation can be used to test dual-message OCT transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate OCT authorization and capture

Action: POST
Endpoint: /simulations/cardtransactions/original.credit.auth_plus_capture

Use this endpoint to simulate original.credit.auth_plus_capture transactions for single-message original credit transaction (OCT) for disbursing funds to a credit card. This simulation can be used to test single-message OCT transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Simulate OCT authorization and capture reversal

Action: POST
Endpoint: /simulations/cardtransactions/original.credit.auth_plus_capture.reversal

Use this endpoint to simulate original.credit.auth_plus_capture.reversal transactions to reverse the financial impact of a single-message original credit transaction (OCT). This simulation can be used to reverse single-message OCT transactions.

See the full request body structure at Request body.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

See the full response body structure at Response body.

Sample response body

JSON
Copied

Is this helpful?

Yes
No