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
/webhooksendpoint 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
Copy section link
| Fields | Description |
|---|---|
card_token
string
|
Unique identifier of the card. Useful when a single account holder has multiple cards. Allowable Values: 36 char max |
card_acceptor
object
|
Contains information about the merchant. Allowable Values: A valid |
card_acceptor.mid
string
|
The merchant identifier. Allowable Values: 2–15 chars |
card_acceptor.mcc
string
|
Merchant category code (MCC). Allowable Values: 5 char max |
card_acceptor.name
string
|
Card acceptor’s name. Allowable Values: 255 char max |
card_acceptor.address
string
|
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
|
Card acceptor’s city. Allowable Values: 255 char max |
card_acceptor.state
string
|
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
|
Card acceptor’s postal code. Allowable Values: 10 char max |
card_acceptor.country_code
string
|
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
|
Amount of the transaction. Allowable Values: 0 min Format: 0.00 |
cash_back_amount
decimal
|
The cashback amount requested. Allowable Values: |
is_preauthorization
boolean
|
Indicates if the transaction is a pre-authorization.
Set to Allowable Values:
|
force_post
boolean
|
Set to NOTE: If you set this field to Allowable Values:
|
fees
array of objects
|
List of fees associated with the transaction. This array is returned if it exists in the resource. Allowable Values: Existing |
fees[].type
string
|
The type of fee assessed by the card network. Allowable Values:
|
fees[].amount
decimal
|
The amount of the network fee. Allowable Values: Format: 0.00 |
fees[].credit_debit
string
|
Indicates whether the fee is a credit or a debit.
Allowable Values:
|
card_options
object
|
Contains attributes that govern card usage Allowable Values: A valid |
card_options.pin
string
|
The PIN for the card. Allowable Values: 4 char max |
card_options.cvv
string
|
The CVV2 number for the card. Allowable Values: 3 chars |
card_options.card_present
boolean
|
A value of Allowable Values:
|
card_options.expiration
string
|
The expiration date of the card. Allowable Values: 4 chars |
card_options.billing_address
object
|
Used for AVS (address verification system). The address-related fields in this object are verified against known values. Allowable Values: A valid |
card_options.billing_address.first_name
string
|
Cardholder’s first name. Allowable Values: To pass AVS, must match the first name on record |
card_options.billing_address.last_name
string
|
Cardholder’s last name. Allowable Values: To pass AVS, must match the last name on record |
card_options.billing_address.address
string
|
Cardholder’s address. Allowable Values: To pass AVS, must match the address on record |
card_options.billing_address.zip
string
|
Cardholder’s postal code. Allowable Values: To pass AVS, must match the postal code on record |
pos
object
|
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.partial_approval_capable
boolean
|
Whether the card acceptor or terminal is capable of partial approvals. Allowable Values:
|
pos.pan_entry_mode
string
|
Entry mode used for transaction. Allowable Values:
|
preceding_related_transaction_token
string
|
Unique identifier of the card. Useful when a single account holder has multiple cards. Allowable Values: 36 char max |
network
string
|
Indicates which card network was used to complete the transaction. Allowable Values:
|
subNetwork
string
|
Indicates which subnetwork used to complete the transaction. Allowable Values:
|
currency_conversion
object
|
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.original_amount
decimal
|
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
|
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 |
currency_conversion.original_currency_code
string
|
The three-digit ISO 4217 currency code. Allowable Values: A valid three-digit ISO 4217 currency code |
currency_code
string
|
Currency type of the transaction. Allowable Values:
|
account_funding
object
|
Information used when funding an account. Allowable Values: A valid |
account_funding.first_name
string
|
Account holder’s first name. Allowable Values: To pass AVS, must match the first name on record. |
account_funding.last_name
string
|
Account holder’s last name. Allowable Values: To pass AVS, must match the last name on record. |
account_funding.receiver_name
string
|
Recipient’s name. Allowable Values: To pass AVS, must match the name on record. |
account_funding.funding_source
string
|
Describes the source of the funding. Allowable Values:
|
account_funding.receiver_account_type
string
|
Identifies the account type used for the funding request. Allowable Values:
|
account_funding.transaction_purpose
string
|
Identifies the purpose of the transaction. Allowable Values:
|
account_funding.transaction_type
string
|
Describes the type of transaction. Allowable Values:
|
original_credit
object
|
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.funding_source
string
|
Describes the source of the funding. Allowable Values:
|
original_credit.transaction_type
string
|
Describes the type of transaction. Allowable Values:
|
original_credit.sender_account_type
string
|
The type of account from which the OCT draws funds. Allowable Values:
|
original_credit.sender_name
string
|
Full name of the sender. Allowable Values: 255 char max |
original_credit.screening_score
string
|
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
Copy section link
| Fields | Description |
|---|---|
transaction
object
|
Contains information about the transaction. Allowable Values: Existing |
transaction.type
string
|
Transaction event type. For more information about the Allowable Values:
|
transaction.state
string
|
Current state of the transaction. For more information about the Allowable Values:
|
transaction.token
string
|
Unique identifier of the transaction, formatted as a UUID. NOTE: For subsequent related transactions, this token value appears as the Allowable Values: 1–36 chars |
transaction.user_token
string
|
Unique identifier of the user who owns the account that funded the transaction; subsequent related transactions retain the same Allowable Values: 36 char max |
transaction.card_token
string
|
Unique identifier of the card. Useful when a single account holder has multiple cards. Allowable Values: 36 char max |
transaction.response
object
|
Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder. Allowable Values: Existing |
transaction.response.code
string
|
Four-digit code corresponding with the outcome of the attempted transaction type.
Allowable Values: Four-digit code |
transaction.response.memo
string
|
Information on the outcome of the attempted transaction type. Allowable Values: 255 char max |
transaction.response.additional_information
string
|
Information about the relevant velocity control for the transaction, if applicable. Allowable Values: The |
transaction.created_time
datetime
|
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
|
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
|
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
|
Amount of the transaction. Allowable Values: Format: 0.00 |
transaction.amount_to_be_released
decimal
|
Amount to released following a financial advice. Allowable Values: Format: 0.00 |
transaction.cash_back_amount
decimal
|
The cashback amount requested. Allowable Values: Format: 0.00 |
transaction.request_amount
decimal
|
Merchant-requested amount, including any fees. This includes amount and cashback amount. Allowable Values: Format: 0.00 |
transaction.gpa
object
|
Contains information about the GPA balances and pending credits. Allowable Values:
|
transaction.gpa.ledger_balance
decimal
|
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
|
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
|
Balance change based on the amount of the transaction. Allowable Values: Format: 0.00 |
transaction.currency_code
string
|
The three-digit ISO 4217 currency code. Allowable Values: A valid three-digit ISO 4217 currency code |
transaction.currency_conversion
object
|
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 |
transaction.currency_conversion.original_amount
decimal
|
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
|
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 |
transaction.currency_conversion.original_currency_code
string
|
The three-digit ISO 4217 currency code. Allowable Values: A valid three-digit ISO 4217 currency code |
transaction.preceding_related_transaction_token
string
|
Returned for final transaction types. Unique identifier of the preceding related transaction.
Useful for identifying the transaction that preceded the current one.
For example, In this case, the Allowable Values: UUID |
transaction.network
string
|
Indicates which card network was used to complete the transaction. Allowable Values:
|
transaction.subnetwork
string
|
Indicates which subnetwork used to complete the transaction. Allowable Values:
|
transaction.acquirer_fee_amount
decimal
|
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
|
List of fees associated with the transaction. This array is returned if it exists in the resource. Allowable Values: Array of existing |
transaction.fees[].type
string
|
The type of fee assessed by the card network. Allowable Values:
|
transaction.fees[].amount
decimal
|
The amount of the network fee. Allowable Values: Format: 0.00 |
transaction.fees[].credit_debit
string
|
Indicates whether the fee is a credit or a debit.
Allowable Values:
|
transaction.fraud
object
|
Contains one or more fraud determinations by the card network that apply to either the transaction or the cardholder’s account. Allowable Values:
|
transaction.fraud.network
object
|
Contains network-provided information about fraud determinations. Allowable Values:
|
transaction.fraud.network.transaction_risk_score
integer
|
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
|
(Mastercard only) Unique code that describes the main driver of the Allowable Values: 1-29 |
transaction.fraud.network.transaction_risk_score_reason_description
string
|
(Mastercard only) Description of the Allowable Values: 255 char max |
transaction.fraud.network.account_risk_score
string
|
(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
|
(Visa only) Unique code that describes the main driver of the Allowable Values: 255 char max |
transaction.card_acceptor
object
|
Contains information about the merchant. Allowable Values: A valid |
transaction.card_acceptor.mid
string
|
The merchant identifier. Allowable Values: 2–15 chars |
transaction.card_acceptor.mcc
string
|
Merchant category code (MCC). Allowable Values: 5 char max |
transaction.card_acceptor.name
string
|
Card acceptor’s name. Allowable Values: 255 char max |
transaction.card_acceptor.address
string
|
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
|
Card acceptor’s city. Allowable Values: 255 char max |
transaction.card_acceptor.state
string
|
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
|
Card acceptor’s postal code. Allowable Values: 10 char max |
transaction.card_acceptor.country_code
string
|
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
|
Information used when funding an account. Allowable Values: A valid |
transaction.account_funding.first_name
string
|
Account holder’s first name. Allowable Values: To pass AVS, must match the first name on record. |
transaction.account_funding.last_name
string
|
Account holder’s last name. Allowable Values: To pass AVS, must match the last name on record. |
transaction.account_funding.receiver_name
string
|
Recipient’s name. Allowable Values: To pass AVS, must match the name on record. |
transaction.account_funding.funding_source
string
|
Describes the source of the funding. Allowable Values:
|
transaction.account_funding.receiver_account_type
string
|
Identifies the account type used for the funding request. Allowable Values:
|
transaction.account_funding.transaction_purpose
string
|
Identifies the purpose of the transaction. Allowable Values:
|
transaction.account_funding.transaction_type
string
|
Describes the type of transaction. Allowable Values:
|
transaction.gpa_order
object
|
Contains information about a GPA order, including fees, funding sources, and addresses. See GPA Orders for more information. Allowable Values: Existing |
transaction.gpa_order.amount
decimal
|
Amount funded. Allowable Values: Format: 0.00 |
transaction.gpa_order.created_time
datetime
|
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
|
The three-digit ISO 4217 currency code. Allowable Values: A valid three-digit ISO 4217 currency code |
transaction.gpa_order.fees
array of objects
|
List of fees associated with the transaction. This array is returned if it exists in the resource. Allowable Values: Array of existing |
transaction.gpa_order.fees[].fee
object
|
Contains details about the fee. Allowable Values:
|
transaction.gpa_order.fees[].fee.active
boolean
|
Indicates whether the fee is active. Allowable Values:
|
transaction.gpa_order.fees[].fee.amount
decimal
|
Amount of the fee. Allowable Values: Format: 0.00 |
transaction.gpa_order.fees[].fee.created_time
datetime
|
Date and time when the Allowable Values: yyyy-MM-ddTHH:mm:ssZ |
transaction.gpa_order.fees[].fee.currency_code
string
|
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
|
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
|
Name of the fee. Allowable Values: 50 char max |
transaction.gpa_order.fees[].fee.real_time_assessment
object
|
Controls the assessment of real-time fees. Allowable Values:
|
transaction.gpa_order.fees[].fee.real_time_assessment.domestic_enabled
boolean
|
Enables fee assessments where the origin of the transaction acquirer is inside the US. Allowable Values:
|
transaction.gpa_order.fees[].fee.real_time_assessment.international_enabled
boolean
|
Enables fee assessments where the origin of the transaction acquirer is outside the US. Allowable Values:
|
transaction.gpa_order.fees[].fee.real_time_assessment.transaction_type
string
|
Indicates the type of transactions on which the fee is assessed. Allowable Values:
|
transaction.gpa_order.fees[].fee.tags
string
|
Descriptive metadata about the fee. Allowable Values: 255 char max |
transaction.gpa_order.fees[].fee.token
string
|
Unique identifier of the Allowable Values: Existing |
transaction.gpa_order.fees[].memo
string
|
Additional text that describes the fee transfer. Allowable Values: 1–99 chars |
transaction.gpa_order.fees[].tags
string
|
Descriptive metadata about the fee. Allowable Values: 255 char max |
transaction.gpa_order.fees[].token
string
|
Unique identifier of the fee. Allowable Values: 1–36 chars |
transaction.gpa_order.fees[].transaction_token
string
|
Unique identifier of the fee transaction. Allowable Values: 36 char max |
transaction.gpa_order.funding
object
|
Contains funding information for the transaction, including funding amount, type, and time. Allowable Values:
|
transaction.gpa_order.funding.amount
decimal
|
Amount of funds loaded into the GPA. Allowable Values: Format: 0.00 |
transaction.gpa_order.funding.gateway_log
object
|
Contains information from the JIT Funding gateway in response to a funding request. Allowable Values:
|
transaction.gpa_order.funding.gateway_log.duration
integer
|
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
|
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:
|
transaction.gpa_order.funding.gateway_log.order_number
string
|
Customer order number, same value as Allowable Values: Existing |
transaction.gpa_order.funding.gateway_log.timed_out
boolean
|
Whether the gateway sent a response ( Allowable Values:
|
transaction.gpa_order.funding.gateway_log.transaction_id
string
|
Customer-defined identifier for the transaction. Allowable Values: 255 char max |
transaction.gpa_order.funding.source
object
|
Contains funding source information for the transaction, including the funding type and time. Allowable Values:
|
transaction.gpa_order.funding.source.active
boolean
|
Whether the funding source is active. Allowable Values:
|
transaction.gpa_order.funding.source.created_time
datetime
|
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
|
Whether the GPA order unload’s funding source is the default funding account. Allowable Values:
|
transaction.gpa_order.funding.source.last_modified_time
datetime
|
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
|
Unique identifier of the funding source. Allowable Values: Format: UUID |
transaction.gpa_order.funding.source.type
string
|
Funding type of the funding source. Allowable Values:
|
transaction.gpa_order.funding.source_address
object
|
Contains information about the billing address of the funding source. Allowable Values:
|
transaction.gpa_order.funding.source_address.active
boolean
|
Whether the address is active. Allowable Values:
|
transaction.gpa_order.funding.source_address.address_1
string
|
Street address of the funding source. Allowable Values: 255 char max |
transaction.gpa_order.funding.source_address.address_2
string
|
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
|
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
|
City of the funding source. Allowable Values: 40 char max |
transaction.gpa_order.funding.source_address.country
string
|
Country of the funding source. Allowable Values: 1–40 chars |
transaction.gpa_order.funding.source_address.created_time
datetime
|
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
|
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
|
Whether this address is the default address used by the funding source. Allowable Values:
|
transaction.gpa_order.funding.source_address.last_modified_time
datetime
|
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
|
Last name of the account holder associated with the funding source. Allowable Values: 40 char max |
transaction.gpa_order.funding.source_address.phone
string
|
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
|
Postal code of the funding source. Allowable Values: 10 char max |
transaction.gpa_order.funding.source_address.state
string
|
Two-character state, province, or territorial abbreviation. For the complete list, see Valid state, provincial, and territorial abbreviations. Allowable Values: 2 char max |
transaction.gpa_order.funding.source_address.token
string
|
Unique identifier of the Allowable Values: 1–36 chars |
transaction.gpa_order.funding.source_address.user_token
string
|
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
|
United States ZIP code of the funding source. Allowable Values: 10 char max |
transaction.gpa_order.funding_source_address_token
string
|
Unique identifier of the funding source address to use for this order. Allowable Values: Existing |
transaction.gpa_order.funding_source_token
string
|
Unique identifier of the funding source to use for this order. Allowable Values: Existing |
transaction.gpa_order.gateway_message
string
|
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:
|
transaction.gpa_order.gateway_token
integer
|
Unique identifier of the funding source to use for this order. Allowable Values: Existing |
transaction.gpa_order.jit_funding
object
|
Contains information about the JIT Funding load event, in which funds are loaded into an account. Allowable Values:
|
transaction.gpa_order.jit_funding.amount
decimal
|
Requested amount of funding. Allowable Values: 0 min |
transaction.gpa_order.jit_funding.balances
object
|
Contains the GPA’s balance details. Allowable Values: Existing |
transaction.gpa_order.jit_funding.business_token
string
|
Holder of the business account that was funded. Allowable Values: 36 char max |
transaction.gpa_order.jit_funding.decline_reason
string
|
Reason why the transaction was declined. Allowable Values:
|
transaction.gpa_order.jit_funding.incremental_authorization_jit_funding_tokens
array of strings
|
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
|
Additional information that describes the JIT Funding transaction. Allowable Values: 99 char max |
transaction.gpa_order.jit_funding.method
string
|
JIT Funding response type. See The jit_funding object for the purpose, funding event type, and description of each method. Allowable Values:
|
transaction.gpa_order.jit_funding.original_jit_funding_token
string
|
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
|
Customer-defined tags related to the JIT Funding transaction. Allowable Values: 255 char max |
transaction.gpa_order.jit_funding.token
string
|
Existing JIT Funding token matching the Allowable Values: 36 char max |
transaction.gpa_order.jit_funding.user_token
string
|
Holder of the user account that was funded. Allowable Values: 36 char max |
transaction.gpa_order.last_modified_time
datetime
|
Date and time when the Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
transaction.gpa_order.memo
string
|
Additional descriptive text. This field is returned if it exists in the resource. Allowable Values: 99 char max |
transaction.gpa_order.response
object
|
Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder. Allowable Values: Existing |
transaction.gpa_order.response.code
string
|
Four-digit code corresponding with the outcome of the attempted transaction type.
Allowable Values: Four-digit code |
transaction.gpa_order.response.memo
string
|
Information on the outcome of the attempted transaction type. Allowable Values: 255 char max |
transaction.gpa_order.response.additional_information
string
|
Information about the relevant velocity control for the transaction, if applicable. Allowable Values: The |
transaction.gpa_order.state
string
|
Current status of the funding transaction. Allowable Values:
|
transaction.gpa_order.tags
string
|
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
|
Unique identifier of the GPA order. Allowable Values: 36 char max |
transaction.gpa_order.transaction_token
string
|
Unique identifier of the transaction being funded. Allowable Values: Format: UUID |
transaction.gpa_order.user_token
string
|
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
|
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 |
transaction.original_credit.funding_source
string
|
Describes the source of the funding. Allowable Values:
|
transaction.original_credit.transaction_type
string
|
Describes the type of transaction. Allowable Values:
|
transaction.original_credit.sender_account_type
string
|
The type of account from which the OCT draws funds. Allowable Values:
|
transaction.original_credit.sender_name
string
|
Full name of the sender. Allowable Values: 255 char max |
transaction.original_credit.screening_score
string
|
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
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate authorization advice
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate authorization reversal
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate incremental authorization
Copy section link
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/authorizationendpoint:
Action:POST
Endpoint:/simulations/cardtransactions/authorization -
Increment the authorization using the
/cardtransactions/authorization.incrementalendpoint:
Action:POST
Endpoint:/simulations/cardtransactions/authorization.incremental
See the full request body structure at Request body.
Sample request body
Copy section link
See the full response body structure at Response body.
Simulate authorization cash back
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate ATM withdrawal authorization
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate ATM withdrawal authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate quasi-cash authorization
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate quasi-cash authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate AFT authorization
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate AFT authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate AFT authorization reversal
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate AFT authorization and capture
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate AFT authorization and capture reversal
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate refund
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate refund authorization
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate refund authorization reversal
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate refund authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit authorization
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit authorization reversal
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit cash back
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit refund
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit ATM withdrawal
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit balance inquiry
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate PIN-debit quasi-cash
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate OCT authorization
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate OCT authorization clearing
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate OCT authorization and capture
Copy section link
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
Copy section link
See the full response body structure at Response body.
Simulate OCT authorization and capture reversal
Copy section link
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
Copy section link
See the full response body structure at Response body.