DOCS
Developer resources
Community

Collaborate on your project with other Marqeta developers

Sales

Speak with an expert to learn more about Marqeta

/
Guides
Core API

Launch and manage your company's payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta's reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

35 minute read
May 17, 2023

Simulating Transactions

Note
This feature is in the process of being deprecated in favor of the updated Simulations 2.0 API for card transactions and direct deposits. To learn more about the beta program for this feature, contact your Marqeta representative.

The Marqeta platform provides you with a production environment, as well as a test environment known as the sandbox.

There are two types of sandbox environments available:

  • Public sandbox: A single-user environment where you can begin building your program. Public sandbox users are typically potential customers who are evaluating Marqeta as a partner in their application.

  • Private sandbox: A multi-user environment where you can integrate your application with the Marqeta platform. Marqeta customers use the private sandbox and its connected microservices to validate their application’s integration, as well as ongoing API changes.

All funds and transactions are simulated in both types of sandbox environments. The sandbox may give you access to features not available in production environments, depending on your integration.

The most significant functional 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.

The public and private sandbox environments, on the other hand, do not communicate with a card network and the cards you create within them cannot be used to conduct real-world transactions. You must, therefore, rely on simulated transactions in order to test the cards, users, and other objects you create within the sandbox.

The public and private sandbox environments provide a set of endpoints that allow you to simulate various types of card network transactions, such as authorizations, reversals, and balance inquiries. These endpoints are available only within the public and private sandbox environments, and not within your production environment. This page, therefore, applies only to the public and private sandbox environments.

Simulate authorization
Copy section link

Action: POST
Endpoint: /simulate/authorization

Sign in to use API widgets
POST

Simulate an authorization type transaction by including the card_token and other authorization details in your request.

Body field details
Copy section link

Fields Description

card_token

string
Required

The unique identifier of the card involved in the transaction.

Allowable Values:

255 char max

amount

decimal
Required

The amount of the transaction.

Allowable Values:

Format: 0.00

mid

string
Required

The Merchant Identifier of the merchant participating in the transaction.

Allowable Values:

50 char max

is_pre_auth

boolean
Optional

Set to true to mark the amount as an authorization only.

Allowable Values:

true, false

Default value:
false

card_acceptor

object
Optional

Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.

card_options

object
Optional

Contains attributes that govern card usage.

Allowable Values:

A valid card_options object.

transaction_options

object
Optional

Contains additional information about the transaction.

Allowable Values:

A valid transaction_options object.

pin

string
Optional

If the transaction involves a PIN-protected account, this is the PIN number.

Allowable Values:

4 char max

cash_back_amount

decimal
Optional

If the transaction simulates authorization for cash back, this is the cash amount.

Allowable Values:

Format: 0.00

network_fees

array of objects
Optional

Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The card_options object
Copy section link

Fields Description

cvv

string
Optional

The CVV2 number for the card.

Allowable Values:

4 char max

expiration

string
Optional

The expiration date of the card.

Allowable Values:

mmdd

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_present

boolean
Optional

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

Allowable Values:

true, false

Default value:
false

The card_options.billing_address object
Copy section link

Fields Description

first_name

string
Optional

Cardholder’s first name.

Allowable Values:

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

last_name

string
Optional

Cardholder’s last name.

Allowable Values:

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

address

string
Optional

Cardholder’s street address.

Allowable Values:

To pass AVS, must match the address on record.

zip

string
Optional

Cardholder’s postal code.

Allowable Values:

To pass AVS, must match the postal code on record.

The card_acceptor object
Copy section link

Fields Description

mcc

string
Optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean
Optional

Whether the response can approve an amount less than or equal to the requested amount.

Allowable Values:

true, false

Default value:
false

name

string
Optional

Merchant name.

Allowable Values:

255 char max

address

string
Optional

Merchant address.

Allowable Values:

255 char max

city

string
Optional

Merchant city.

Allowable Values:

255 char max

state

string
Optional

Merchant state.

Allowable Values:

2 char max

zip

string
Optional

Merchant ZIP or postal code.

Allowable Values:

10 char max

country

string
Optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string
Optional

Contains the fields representing the security protocol and cardholder authentication type associated with the transaction.

Allowable Values:

0-9

The transaction_options object
Copy section link

Fields Description

additional_data

string
Optional

Additional information about the transaction.

Allowable Values:

255 char max

The network_fees object
Copy section link

Fields Description

type

string
Required

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

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

amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

credit_debit

string
Optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Simulate authorization advice
Copy section link

Action: POST
Endpoint: /simulate/authorization/advice

Sign in to use API widgets
POST

An authorization advice allows an amount to be decreased after the authorization. This endpoint allows you to simulate post-swipe adjustments.

Simulate an authorization.advice type transaction by including the original_transaction_token and other authorization details in your request.

Body field details
Copy section link

Fields Description

amount

decimal
Required

The amount of the transaction.

Allowable Values:

Format: 0.00

original_transaction_token

string
Required

The unique token that identifies the original transaction.

Allowable Values:

Existing transaction token.

transaction_options

object
Optional

Contains additional information about the transaction.

Allowable Values:

network_fees

array of objects
Optional

Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The transaction_options object
Copy section link

Fields Description

additional_data

string
Optional

Additional information about the transaction.

Allowable Values:

255 char max

The network_fees object
Copy section link

Fields Description

type

string
Required

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

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

amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

credit_debit

string
Optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Simulate clearing or refund
Copy section link

Action: POST
Endpoint: /simulate/clearing

Sign in to use API widgets
POST

Simulate an authorization.clearing type transaction by including the original_transaction_token and amount in your request. To simulate a refund type transaction, set the is_refund field to true.

Body field details
Copy section link

Fields Description

original_transaction_token

string
Required

The unique identifier of the transaction to clear.

Allowable Values:

Existing transaction token.

amount

decimal
Required

The amount of the transaction.

Allowable Values:

Format: 0.00

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

Default value:
false

is_refund

boolean
Optional

Set to true to simulate a refund transaction.

Allowable Values:

true, false

Default value:
false

mid

string
Optional

Merchant Identification number.

Allowable Values:

50 char max

card_acceptor

object
Optional

Contains attributes that describe the merchant.

Allowable Values:

network_fees

array of objects
Optional

Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The card_acceptor object
Copy section link

Fields Description

mcc

string
Optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean
Optional

Whether the response can approve an amount less than or equal to the requested amount.

Allowable Values:

true, false

Default value:
false

name

string
Optional

Merchant name.

Allowable Values:

255 char max

address

string
Optional

Merchant address.

Allowable Values:

255 char max

city

string
Optional

Merchant city.

Allowable Values:

255 char max

state

string
Optional

Merchant state.

Allowable Values:

2 char max

zip

string
Optional

Merchant ZIP or postal code.

Allowable Values:

10 char max

country

string
Optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string
Optional

Contains the fields representing the security protocol and cardholder authentication type associated with the transaction.

Allowable Values:

0-9

The network_fees object
Copy section link

Fields Description

type

string
Required

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

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

amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

credit_debit

string
Optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

Send the following request to simulate an authorization.clearing type transaction.

JSON
Copied

Is this helpful?

Yes
No

Send the following request to simulate a refund type transaction.

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

The following response shows an authorization.clearing type transaction.

JSON
Copied

Is this helpful?

Yes
No

The following response shows a refund type transaction.

JSON
Copied

Is this helpful?

Yes
No

Simulate financial
Copy section link

Action: POST
Endpoint: /simulate/financial

Sign in to use API widgets
POST

A "financial" is a transaction message class that includes ATM transactions, PIN-debit transactions, and balance inquiries.

Simulate a pindebit type transaction by including the card_token and amount in your request.

Body field details
Copy section link

Fields Description

amount

decimal
Required

The transaction amount.

Allowable Values:

Format: 0.00

mid

string
Required

Merchant Identification number

Allowable Values:

50 char max

card_token

string
Required

The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.

pin

string
Optional

The PIN number for the associated card, if required.

Allowable Values:

4 char max

is_pre_auth

boolean
Optional

Set to true to mark the amount as an authorization only.

Allowable Values:

true, false

Default value:
false

cash_back_amount

decimal
Optional

The cash-back amount.

Allowable Values:

Format: 0.00

transaction_options

object
Optional

Contains additional information about the transaction.

Allowable Values:

A valid transaction_options object.

card_acceptor

object
Optional

Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The card_acceptor object
Copy section link

Fields Description

mcc

string
Optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean
Optional

Whether the response can approve an amount less than or equal to the requested amount.

Allowable Values:

true, false

Default value:
false

name

string
Optional

Merchant name.

Allowable Values:

255 char max

address

string
Optional

Merchant address.

Allowable Values:

255 char max

city

string
Optional

Merchant city.

Allowable Values:

255 char max

state

string
Optional

Merchant state.

Allowable Values:

2 char max

zip

string
Optional

Merchant ZIP or postal code.

Allowable Values:

10 char max

country

string
Optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string
Optional

Contains the fields representing the security protocol and cardholder authentication type associated with the transaction.

Allowable Values:

0-9

The transaction_options object
Copy section link

Fields Description

additional_data

string
Optional

Attribute of the transaction_options object. Contains additional information about the transaction.

Allowable Values:

A valid additional_data object.

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Simulate financial advice
Copy section link

Action: POST
Endpoint: /simulate/financial/advice

Sign in to use API widgets
POST

Simulate a financial advice by including the original_transaction_token and other authorization details in JSON format in the body of the request.

Body field details
Copy section link

Fields Description

amount

decimal
Required

The transaction amount.

Allowable Values:

Format: 0.00

original_transaction_token

string
Required

The unique identifier of the original transaction.

Allowable Values:

Existing transaction token.

transaction_options

object
Optional

Contains additional information about the transaction.

Allowable Values:

A valid transaction_options object.

network_fees

array of objects
Optional

Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The transaction_options object
Copy section link

Fields Description

additional_data

string
Optional

Attribute of the transaction_options object. Contains additional information about the transaction.

Allowable Values:

A valid additional_data object.

The network_fees object
Copy section link

Fields Description

type

string
Required

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

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

amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

credit_debit

string
Optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

The following response shows a pindebit.authorization.clearing type transaction.

JSON
Copied

Is this helpful?

Yes
No

Simulate balance inquiry
Copy section link

Action: POST
Endpoint: /simulate/financial/balanceinquiry

Sign in to use API widgets
POST

Simulate a pindebit.balanceinquiry type transaction by sending a POST request to the /simulate/financial/balanceinquiry endpoint.

Body field details
Copy section link

Fields Description

mid

string
Required

Merchant Identification number

Allowable Values:

50 char max

card_token

string
Required

The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.

pin

string
Optional

The PIN number for the associated card, if required.

Allowable Values:

4 char max

account_type

string
Required

The type of account – checking, savings, credit card.

Allowable Values:

checking, savings, credit

card_acceptor

object
Optional

Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.

network_fees

array of objects
Optional

Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The card_acceptor object
Copy section link

Fields Description

mcc

string
Optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean
Optional

Whether the response can approve an amount less than or equal to the requested amount.

Allowable Values:

true, false

Default value:
false

name

string
Optional

Merchant name.

Allowable Values:

255 char max

address

string
Optional

Merchant address.

Allowable Values:

255 char max

city

string
Optional

Merchant city.

Allowable Values:

255 char max

state

string
Optional

Merchant state.

Allowable Values:

2 char max

zip

string
Optional

Merchant ZIP or postal code.

Allowable Values:

10 char max

country

string
Optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string
Optional

Contains the fields representing the security protocol and cardholder authentication type associated with the transaction.

Allowable Values:

0-9

The network_fees object
Copy section link

Fields Description

type

string
Required

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

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

amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

credit_debit

string
Optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Simulate ATM withdrawal
Copy section link

Action: POST
Endpoint: /simulate/financial/withdrawal

Sign in to use API widgets
POST

Simulate a pindebit.atm.withdrawal type transaction by including the card_token and amount in your request.

Body field details
Copy section link

Fields Description

mid

string
Required

Merchant Identification number.

Allowable Values:

50 char max

card_token

string
Required

The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.

pin

string
Optional

The PIN number for the associated card, if required.

Allowable Values:

4 char max

account_type

string
Required

The type of account – checking, savings, credit card.

Allowable Values:

checking, savings, credit

amount

decimal
Required

The amount of money to withdraw.

Allowable Values:

Format: 0.00

card_acceptor

object
Optional

Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The card_acceptor object
Copy section link

Fields Description

mcc

string
Optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean
Optional

Whether the response can approve an amount less than or equal to the requested amount.

Allowable Values:

true, false

Default value:
false

name

string
Optional

Merchant name.

Allowable Values:

255 char max

address

string
Optional

Merchant address.

Allowable Values:

255 char max

city

string
Optional

Merchant city.

Allowable Values:

255 char max

state

string
Optional

Merchant state.

Allowable Values:

2 char max

zip

string
Optional

Merchant ZIP or postal code.

Allowable Values:

10 char max

country

string
Optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string
Optional

Contains the fields representing the security protocol and cardholder authentication type associated with the transaction.

Allowable Values:

0-9

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Simulate reversal
Copy section link

Action: POST
Endpoint: /simulate/reversal

Sign in to use API widgets
POST

A reversal releases the hold that was placed on account funds by an authorization, thus returning the funds to the account.

Simulate an authorization.reversal type transaction by including the original_transaction_token and amount in your request.

Body field details
Copy section link

Fields Description

original_transaction_token

string
Required

The unique identifier of the transaction to reverse.

Allowable Values:

Existing transaction token.

amount

decimal
Required

The amount of the transaction.

Allowable Values:

Format: 0.00

network_fees

array of objects
Optional

Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The network_fees object
Copy section link

Fields Description

type

string
Required

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

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

amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

credit_debit

string
Optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Simulate direct deposit
Copy section link

Action: POST
Endpoint: /simulate/directdeposits

Sign in to use API widgets
POST

Simulate a direct deposit of funds to a user account by including the deposit account number of the account to be debited or credited. You can find the account number in the account_number field of the response when you create a new deposit account. Alternatively, you can retrieve it by sending a GET request to the /depositaccounts/user/{user_token} endpoint. For more information, see Direct Deposits.

If type is CREDIT, the response contains a simulated transaction message (i.e., a direct deposit record) and the corresponding transaction that is created is of the type directdeposit.credit.pending. If type is DEBIT, the response contains a simulated transaction message (i.e., a direct deposit record) and the corresponding transaction that is created is of the type directdeposit.debit.pending.

This endpoint returns a directdeposit object with a direct deposit token, and its state will be PENDING. Calling this endpoint does not return the transactions object; you cannot take the token from the response and look up the direct deposit record using the /transactions endpoint. You can, however, look it up by sending a GET request to the /directdeposits/token endpoint.

Note
You can use this endpoint to simulate directdeposit.credit.pending and directdeposit.debit.pending events only. Simulating other types of events is not currently supported.

Body field details
Copy section link

Fields Description

amount

string
Required

The amount of the direct deposit.

Allowable Values:

Format: 0.00

type

string
Required

Indicates whether the direct deposit is a debit or credit.

Allowable Values:

CREDIT, DEBIT

account_number

string
Required

The account number of the user to debit or credit.

Allowable Values:

An account number belonging to an active user with an active card.

Send a GET request to the /depositaccounts/user/{user_token} endpoint to retrieve the account number of a user.

settlement_date

string
Required

The date on which the credit or debit will be applied.

Allowable Values:

Format: yyyy-MM-dd

Sample requests
Copy section link

Send the following request to simulate a directdeposit.credit.pending type transaction.

JSON
Copied

Is this helpful?

Yes
No

Send the following request to simulate a directdeposit.debit.pending type transaction.

JSON
Copied

Is this helpful?

Yes
No

Sample responses
Copy section link

The following response shows a directdeposit.credit.pending type transaction.

Note that the state of the direct deposit is PENDING. You now need to use the Direct Deposit Transitions endpoint /directdeposits/transitions to transition the pending direct deposit to either APPLIED (to settle the direct deposit) or REVERSED (to fail the direct deposit).

JSON
Copied

Is this helpful?

Yes
No

The following response shows a directdeposit.debit.pending type transaction.

Note that the state of the direct deposit is PENDING. You now need to use the Direct Deposit Transitions endpoint /directdeposits/transitions to transition the pending direct deposit to either APPLIED (to settle the direct deposit) or REVERSED (to fail the direct deposit).

JSON
Copied

Is this helpful?

Yes
No

Simulate OCT
Copy section link

Action: POST
Endpoint: /simulate/financial/originalcredit

Sign in to use API widgets
POST

This Original Credit Transaction (OCT) enables the cardholder to receive funds on the specified card from an external source via the card network. Use this endpoint to simulate a transaction that is similar to a wire transfer and not linked to any purchase.

Simulate an OCT by including the card_token, amount, mid, and type in your request.

Body field details
Copy section link

Fields Description

amount

decimal
Required

Amount of the transaction.

Allowable Values:

Format: 0.00

Must be greater than zero

card_token

string
Required

Unique identifier of the card receiving original credit.

Allowable Values:

Existing card token.

36 char max

mid

string
Required

Merchant Identifier of the merchant participating in the transaction.

Allowable Values:

50 char max

card_acceptor

object
Optional

Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.

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.

Allowable Values:

000-100 or 999

Value of 999 means no score available.

type

string
Required

Type of original credit 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

sender_data

object
Optional

Contains sender-related information.

Allowable Values:

A valid sender_data object.

webhook

object
Optional

Allows information to be posted asynchronously to endpoints hosted in your environment.

Allowable Values:

A valid webhook object.

The card_acceptor object
Copy section link

Fields Description

mcc

string
Optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean
Optional

Whether the response can approve an amount less than the requested amount.

Allowable Values:

true, false

Default value:
false

name

string
Optional

Merchant name.

Allowable Values:

255 char max

address

string
Optional

Merchant address.

Allowable Values:

255 char max

city

string
Optional

Merchant city.

Allowable Values:

255 char max

state

string
Optional

Merchant state.

Allowable Values:

2 char max

zip

string
Optional

Merchant ZIP or postal code.

Allowable Values:

10 char max

country

string
Optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string
Optional

Represents the security protocol and cardholder authentication type associated with the transaction.

Allowable Values:

0-9

The sender_data object
Copy section link

Fields Description

sender_name

string
Optional

Sender full name.

Allowable Values:

255 char max

sender_reference_number

string
Optional

Transaction reference number provided by the originating bank used to uniquely identify the sender

Allowable Values:

16 char max

sender_account_number

string
Optional

Sender’s simulated account number.

Allowable Values:

34 char max

sender_address

string
Optional

Sender street address.

Allowable Values:

255 char max

sender_city

string
Optional

Sender city.

Allowable Values:

36 char max

sender_state

string
Optional

Sender state.

Allowable Values:

2 char max

sender_country

string
Optional

Sender country.

Allowable Values:

40 char max

funding_source

string
Optional

Sender’s simulated account from which the OCT draws funds.

Allowable Values:

credit, debit, prepaid, deposit_account, cash, mobile_money_account, non_visa_credit

The webhook object
Copy section link

Fields Description

endpoint

string
Optional

Endpoint to which a copy of the response is sent.

Allowable Values:

  • HTTPS URL

  • 250 char max

  • Empty string not allowed

username

string
Optional

Username for accessing the endpoint.

Allowable Values:

50 char max

password

string
Optional

Password for accessing the endpoint.

Allowable Values:

No restrictions

Sample request body
Copy section link

Send the following request to simulate a disbursement type transaction.

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

The following response simulates a disbursement type transaction.

JSON
Copied

Is this helpful?

Yes
No

Related materials

Subscribe to our developer newsletter

© 2023 Marqeta, Inc.

• Terms • API Terms • Privacy • Cookies
Back to Marqeta.com