Skip to main content
Hidden This page shows you how to test a specific set of transaction types using the /simulate/advanced API endpoint. You will not find comprehensive documentation of this endpoint here. Any interactions not described below are unsupported.
Note
Distribution of this page is limited; all information contained herein is confidential.
For information about using the public /simulate endpoint, see Simulating Transactions.

​
Simulate Automated Teller Machine (ATM) withdrawals with fees

Simulate a pindebit.atm.withdrawal type authorization transaction, including fees, by including the card_token, amount, and network_fees object parameters with the request. Action: POST
Endpoint: /simulate/advanced/authorization

​
Body field details

FieldsDescription
mid

string

Optional		Merchant ID. The unique identification number of a merchant.

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

Conditionally required		The PIN number for the associated card.

Required when the transaction involves a PIN-protected account. This requirement may be set at the program level.

Allowable Values:

4 char max
amount

number

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

array of objects

Optional		Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.
mti

string

Required		ISO 8583 message type indicator.

Allowable Values:

- 0100 for dual-message transactions
- 0200 for single-message transactions such as ATM withdrawals
processing_code

string

Conditionally required		Internal Marqeta field.

Required when the value of mti is 0200.

Allowable Values:

01
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

FieldsDescription
mcc

string

Optional		Merchant category code.

Allowable Values:

5 char max
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

​
The network_fees object

FieldsDescription
type

string

Optional		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.
- CROSS_BORDER_CARDHOLDER_FEE – Cross-border fee charged to the cardholder by the card network. Impacts 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
CROSS_BORDER_CARDHOLDER_FEE / D

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body

JSON
{
  "amount": 20,
  "card_token": "124d8c1d-a7f7-4a9f-8dad-478d31b0605d",
  "mid": "1234",
  "network": "VISA",
  "sub_network": "VISANET",
  "processing_code": "01",
  "pin": "2641",
  "network_fees": [
    {
      "type": "PINDEBIT_ASSOC_FEE",
      "amount": 0.25,
      "credit_debit": "D"
    }
  ],
  "mti": "0100"
}

​
Sample response body

JSON
{
  "transaction": {
    "type": "authorization.atm.withdrawal",
    "state": "PENDING",
    "identifier": "760",
    "token": "200c6e54-f87b-439a-955f-d7c9a1453349",
    "user_token": "2cdc65cd-8c24-4268-aea2-56d36f40323f",
    "acting_user_token": "2cdc65cd-8c24-4268-aea2-56d36f40323f",
    "card_token": "124d8c1d-a7f7-4a9f-8dad-478d31b0605d",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 1000,
      "available_balance": 979.75,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -20.25,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 1000,
          "available_balance": 979.75,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -20.25
        }
      }
    },
    "duration": 326,
    "created_time": "2020-11-17T00:26:01Z",
    "user_transaction_time": "2020-11-17T00:26:01Z",
    "settlement_date": "2020-11-16T08:00:00Z",
    "request_amount": 20.25,
    "amount": 20,
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "552857",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0.25,
    "acquirer": {
      "retrieval_reference_number": "0000518845055968",
      "system_trace_audit_number": "917672"
    },
    "fees": [
      {
        "type": "PINDEBIT_ASSOC_FEE",
        "amount": 0.25,
        "credit_debit": "D"
      }
    ],
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "1718",
      "metadata": {}
    },
    "issuer_received_time": "2020-11-16T16:26:01.707Z",
    "issuer_payment_node": "03d27ab89474890aeced970b68ac904e",
    "network_reference_id": "555983675431",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA",
      "poi": {
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "ATM",
        "pin_present": "true"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Simulate transactions from different card networks

Simulate a transaction across the different card networks and subnetworks by including values for network and sub_network in your request.
Note
You do not have to include sub_network in the request. Visa defaults to VISANET, Mastercard defaults to MAESTRO, and Pulse and Discover do not have subnetworks.
Action: POST
Endpoint: /simulate/advanced/authorization

​
Body field details

FieldsDescription
mid

string

Optional		Merchant ID. The unique identification number of a merchant.

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

Conditionally required		The PIN number for the associated card.

Required when the transaction involves a PIN-protected account. This requirement may be set at the program level.

Allowable Values:

4 char max
network

string

Required		Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, DISCOVER, PULSE
sub_network

string

Optional		Indicates which subnetwork was used to complete the transaction.

NOTE: This field is called sub_network in the request, but is returned in the response as subnetwork.

Allowable Values:

- VISANET – Used for VisaNet signature-based transactions.
- VISANETDEBIT – Used for VisaNet Debit PIN-based transaction.
- VISAINTERLINK – Used for Visa Interlink PIN-based transactions.
- VISAPLUS – Used for ATM withdrawals on Visa.
- MAESTRO – Used for PIN-based transactions on Mastercard.
- CIRRUS – Used for ATM withdrawals on Mastercard.
- MASTERCARDDEBIT – Used for signature-based transactions on Mastercard.
- GATEWAY_JIT – Used for Gateway JIT Funding transactions.
- MANAGED_JIT – Used for Managed JIT Funding transactions or for transactions that occur while Commando Mode is enabled.
amount

number

Required		The amount of the transaction.

Allowable Values:

Format: 0.00
card_acceptor

object

Optional		Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.
mti

string

Required		ISO 8583 message type indicator.

Allowable Values:

- 0100 for dual-message transactions
- 0200 for single-message transactions such as ATM withdrawals
processing_code

string

Conditionally required		Internal Marqeta field.

Required when the value of mti is 0200.

Allowable Values:

01
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

FieldsDescription
mcc

string

Optional		Merchant category code.

Allowable Values:

5 char max
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

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body

JSON
{
  "amount": 23.47,
  "card_token": "23695ffc-1687-4213-9599-08455e55c508",
  "mid": "1234",
  "network": "MASTERCARD",
  "mti": "0100"
}

​
Sample response body

JSON
{
  "transaction": {
    "type": "authorization",
    "state": "PENDING",
    "identifier": "762",
    "token": "b2e4ddb2-6757-49d9-9a8d-41df3b7febac",
    "user_token": "f700afb8-94f8-4bfa-b985-56882c701f94",
    "acting_user_token": "f700afb8-94f8-4bfa-b985-56882c701f94",
    "card_token": "23695ffc-1687-4213-9599-08455e55c508",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 1000,
      "available_balance": 976.53,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -23.47,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 1000,
          "available_balance": 976.53,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -23.47
        }
      }
    },
    "duration": 47,
    "created_time": "2020-11-17T00:28:48Z",
    "user_transaction_time": "2020-11-17T00:28:48Z",
    "settlement_date": "2020-11-16T08:00:00Z",
    "request_amount": 23.47,
    "amount": 23.47,
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "820015",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "MASTERCARD",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "retrieval_reference_number": "0000310848159675",
      "system_trace_audit_number": "287594"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "0874",
      "metadata": {}
    },
    "issuer_received_time": "2020-11-16T16:28:48.853Z",
    "issuer_payment_node": "03d27ab89474890aeced970b68ac904e",
    "network_reference_id": "576938107421",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA",
      "poi": {
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "pin_present": "false"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Simulate transactions with different modes of entry

Use this endpoint to simulate points of interaction with cards. When simulating transactions, you can test various modes of PAN entry for transactions—such as tapping a card versus swiping it—by including different values for the pos_pan_entry_mode field in your request.
Note
The value for pos_pan_entry_mode in your request is not included in the response.
Action: POST
Endpoint: /simulate/advanced/transactions

​
Body field details

FieldsDescription
mid

string

Optional		Merchant ID. The unique identification number of a merchant.

Allowable Values:

50 char max
card_token

string

Required		The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.
pos_pan_entry_mode

string

Conditionally required		How the card PAN was captured at the point of sale.

The Marqeta platform supports different values, depending on which network was specified using the network field. The following table lists the supported PAN capture methods per network:

Visa / Mastercard / Pulse / Discover
MAG_STRIPE / MAG_STRIPE / MAG_STRIPE / None
MANUAL / MANUAL / MANUAL
CARD_ON_FILE / CARD_ON_FILE / CARD_ON_FILE
CHIP_FALLBACK / CHIP_FALLBACK / BAR_CODE
/ / OCR

Allowable Values:

- MAG_STRIPE – Magnetic stripe card’s swipe method was used.
- MANUAL – Card PAN was entered manually.
- CARD_ON_FILE – Merchant initiated the transaction using card information stored on file.
- CHIP_FALLBACK – Chip card was processed as a magnetic stripe transaction.
- BAR_CODE – Bar code was used.
- OCR – Optical code reader was used.
pin

string

Conditionally required		The PIN number for the associated card.

Required when the transaction involves a PIN-protected account. This requirement may be set at the program level.

Allowable Values:

4 char max
network

string

Required		Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, DISCOVER, PULSE
sub_network

string

Optional		Indicates which subnetwork was used to complete the transaction.

NOTE: This field is called sub_network in the request, but is returned in the response as subnetwork.

Allowable Values:

- VISANET – Used for VisaNet signature-based transactions.
- VISANETDEBIT – Used for VisaNet Debit PIN-based transaction.
- VISAINTERLINK – Used for Visa Interlink PIN-based transactions.
- VISAPLUS – Used for ATM withdrawals on Visa.
- MAESTRO – Used for PIN-based transactions on Mastercard.
- CIRRUS – Used for ATM withdrawals on Mastercard.
- MASTERCARDDEBIT – Used for signature-based transactions on Mastercard.
- GATEWAY_JIT – Used for Gateway JIT Funding transactions.
- MANAGED_JIT – Used for Managed JIT Funding transactions or for transactions that occur while Commando Mode is enabled.
amount

number

Required		The amount of the transaction.

Allowable Values:

Format: 0.00
card_acceptor

object

Optional		Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.
mti

string

Required		ISO 8583 message type indicator.

Allowable Values:

- 0100 for dual-message transactions
- 0200 for single-message transactions such as ATM withdrawals
processing_code

string

Conditionally required		Internal Marqeta field.

Required when the value of mti is 0200.

Allowable Values:

01
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

FieldsDescription
mcc

string

Optional		Merchant category code.

Allowable Values:

5 char max
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

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body

JSON
{
  "amount": 23.47,
  "card_token": "d137887b-6288-486a-948b-22912120dad3",
  "mid": "1234",
  "pos_pan_entry_mode": "MAG_STRIPE",
  "network": "VISA",
  "mti": "0100"
}

​
Sample response body

JSON
{
  "transaction": {
    "type": "authorization",
    "state": "PENDING",
    "identifier": "765",
    "token": "5010631e-6b98-4102-a59f-01d2450f1d90",
    "user_token": "58ad8a9a-959c-4a9f-b2ca-092a2adbf4e4",
    "acting_user_token": "58ad8a9a-959c-4a9f-b2ca-092a2adbf4e4",
    "card_token": "d137887b-6288-486a-948b-22912120dad3",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 1000,
      "available_balance": 976.53,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -23.47,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 1000,
          "available_balance": 976.53,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -23.47
        }
      }
    },
    "duration": 259,
    "created_time": "2020-11-17T00:58:24Z",
    "user_transaction_time": "2020-11-17T00:58:24Z",
    "settlement_date": "2020-11-16T08:00:00Z",
    "request_amount": 23.47,
    "amount": 23.47,
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "800121",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "retrieval_reference_number": "0000488153713239",
      "system_trace_audit_number": "352982"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "5401",
      "metadata": {}
    },
    "issuer_received_time": "2020-11-16T16:58:24.078Z",
    "issuer_payment_node": "03d27ab89474890aeced970b68ac904e",
    "network_reference_id": "822292229874",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA",
      "poi": {
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "pin_present": "false"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Simulate international transactions

Simulate international transactions using the local_currency_code and settlement_currency_code fields. Action: POST
Endpoint: /simulate/advanced/authorization

​
Body field details

FieldsDescription
mid

string

Optional		Merchant ID. The unique identification number of a merchant.

Allowable Values:

50 char max
card_token

string

Required		The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.
local_transaction_amount

number

Optional		Amount paid in the currency used to complete the transaction.

Allowable Values:

Format: 0.00
local_currency_code

string

Optional		Currency code for the country where the transaction took place.

Allowable Values:

ISO 4217 currency codes, either alphabetic or numeric
settlement_currency_code

string

Optional		Currency code for the country where the transaction was settled. If not provided, the default currency is USD.

Allowable Values:

ISO 4217 currency codes, either alphabetic or numeric
cardholder_billing_conversion_rate

number

Optional		Ratio between the amount the payee receives in their local currency, and the amount the cardholder pays in the currency of their account. Should be defined for multi-currency transactions.

Allowable Values:

Greater than zero.
pin

string

Conditionally required		The PIN number for the associated card.

Required when the transaction involves a PIN-protected account. This requirement may be set at the program level.

Allowable Values:

4 char max
network

string

Required		Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, DISCOVER, PULSE
amount

number

Required		The amount of the transaction.

Allowable Values:

Format: 0.00
card_acceptor

object

Optional		Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.
mti

string

Required		ISO 8583 message type indicator.

Allowable Values:

- 0100 for dual-message transactions
- 0200 for single-message transactions such as ATM withdrawals
processing_code

string

Conditionally required		Internal Marqeta field.

Required when the value of mti is 0200.

Allowable Values:

01
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

FieldsDescription
mcc

string

Optional		Merchant category code.

Allowable Values:

5 char max
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

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
The currency_conversion object

FieldsDescription
network

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 network object.
network.original_amount

number

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

number

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|OPEN|| CALLOUTTITLE:Note|TITLEBREAK|A value of 0 or 1 indicates no conversion; the currencies are the same. NOTE|CLOSE
network.original_currency_code

string

Conditionally returned		Currency type of the origination currency.

Returned if the transaction involves currency conversion.

Allowable Values:

A valid three-digit ISO 4217 currency type.

​
Sample request body

JSON
{
  "card_token": "c057bb66-9f6d-4e24-9d8b-6f525aa596c3",
  "network": "VISA",
  "local_transaction_amount": "30.00",
  "local_currency_code": "GBP",
  "amount": 37.5,
  "settlement_currency_code": "USD",
  "cardholder_billing_conversion_rate": "1.25",
  "mid": "1234"
}

​
Sample response body

JSON
{
  "transaction": {
    "type": "authorization",
    "state": "PENDING",
    "identifier": "3017",
    "token": "832ab846-8b2f-483d-b21d-901bf5d282b5",
    "user_token": "e65b5845-f627-4cfb-9b71-5338e93f2035",
    "acting_user_token": "e65b5845-f627-4cfb-9b71-5338e93f2035",
    "card_token": "c057bb66-9f6d-4e24-9d8b-6f525aa596c3",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 1000,
      "available_balance": 962.5,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -37.5,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 1000,
          "available_balance": 962.5,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -37.5
        }
      }
    },
    "duration": 81,
    "created_time": "2020-12-11T01:32:45Z",
    "user_transaction_time": "2020-12-11T01:32:45Z",
    "settlement_date": "2020-12-10T08:00:00Z",
    "request_amount": 37.5,
    "amount": 37.5,
    "currency_conversion": {
      "network": {
        "original_amount": 30,
        "conversion_rate": 1.25,
        "original_currency_code": "826"
      }
    },
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "887199",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "retrieval_reference_number": "0000739426359419",
      "system_trace_audit_number": "267079"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "7349",
      "metadata": {}
    },
    "issuer_received_time": "2020-12-10T17:32:45.387Z",
    "issuer_payment_node": "03d27ab89474890aeced970b68ac904e",
    "network_reference_id": "297132240697",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA",
      "poi": {
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "pin_present": "false"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Simulate international ATM withdrawals

Simulate international ATM withdrawals using the local_currency_code and settlement_currency_code fields. Action: POST
Endpoint: /simulate/advanced/authorization

​
Body field details

FieldsDescription
mid

string

Optional		Merchant ID. The unique identification number of a merchant.

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

Conditionally required		The PIN number for the associated card.

Required when the transaction involves a PIN-protected account. This requirement may be set at the program level.

Allowable Values:

4 char max
amount

number

Required		The amount of money to withdraw.

Allowable Values:

Format: 0.00
local_transaction_amount

number

Optional		Amount withdrawn in the currency used to complete the transaction.

Allowable Values:

Format: 0.00
local_currency_code

string

Optional		Currency code for the country where the withdrawal took place.

Allowable Values:

ISO 4217 currency codes, either alphabetic or numeric
settlement_currency_code

string

Optional		Currency code for the country where the transaction was settled. If not provided, the default currency is USD.

Allowable Values:

ISO 4217 currency codes, either alphabetic or numeric
cardholder_billing_conversion_rate

number

Optional		Ratio between the amount the cardholder withdrew in the local currency, and the amount in the currency of the account. Should be defined for multi-currency transactions.

Allowable Values:

Greater than zero.
card_acceptor

object

Optional		Contains attributes that describe the merchant.

Allowable Values:

A valid card_acceptor object.
mti

string

Required		ISO 8583 message type indicator.

Allowable Values:

- 0100 for dual-message transactions
- 0200 for single-message transactions such as ATM withdrawals
processing_code

string

Conditionally required		Internal Marqeta field.

Required when the value of mti is 0200.

Allowable Values:

01
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

FieldsDescription
mcc

string

Optional		Merchant category code.

Allowable Values:

5 char max
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

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body

JSON
{
  "card_token": "124d8c1d-a7f7-4a9f-8dad-478d31b0605d",
  "mid": "1234",
  "network": "VISA",
  "mti": "0200",
  "processing_code": "01",
  "pin": "1661",
  "amount": 37.5,
  "local_transaction_amount": 30,
  "local_currency_code": "GBP",
  "settlement_currency_code": "USD",
  "cardholder_billing_conversion_rate": 1.25
}

​
Sample response body

JSON
{
  "transaction": {
    "type": "pindebit.atm.withdrawal",
    "state": "COMPLETION",
    "identifier": "36",
    "token": "29817fee-fe9a-4470-91ea-0092cdca13e5",
    "user_token": "3766ddc9-cd1b-434b-b708-2dd9601bac38",
    "acting_user_token": "3766ddc9-cd1b-434b-b708-2dd9601bac38",
    "card_token": "196a09c1-0717-45f4-b123-3c7d4fa2f227",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 999887.5,
      "available_balance": 998922.5,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -37.5,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 999887.5,
          "available_balance": 998922.5,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -37.5
        }
      }
    },
    "duration": 408,
    "created_time": "2021-03-22T18:12:15Z",
    "user_transaction_time": "2021-03-22T18:12:15Z",
    "settlement_date": "2021-03-22T07:00:00Z",
    "request_amount": 37.5,
    "amount": 37.5,
    "currency_conversion": {
      "network": {
        "original_amount": 30,
        "conversion_rate": 1.25,
        "original_currency_code": "826"
      }
    },
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "198655",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "retrieval_reference_number": "0000694617956917",
      "system_trace_audit_number": "129890"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "3270",
      "metadata": {}
    },
    "issuer_received_time": "2021-03-22T11:12:15.079Z",
    "issuer_payment_node": "03d27ab89474890aeced970b68ac904e",
    "network_reference_id": "312827359224",
    "acquirer_reference_data": "833277335348",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA",
      "poi": {
        "partial_approval_capable": "1",
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "ATM",
        "pin_present": "true"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Simulate incremental authorization transactions

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. They enable 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 /simulate/advanced/transactions endpoint:
    Action: POST
    Endpoint: /simulate/advanced/transactions
  • Increment the authorization using the /simulate/advanced/authorization/incremental endpoint:
    Action: POST
    Endpoint: /simulate/advanced/authorization/incremental
The body field descriptions below apply equally to both these endpoints.

​
Body field details (create authorization)

FieldsDescription
card_token

string

Required		The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.
amount

number

Required		The amount of the transaction.

Allowable Values:

Format: 0.00
network_reference_id

string

Required		The unique identifier of the transaction to increment.

Supplied by the card network.

Allowable Values:

Depends on the card network
merchant_id

string

Required		Merchant ID. The unique identification number of a merchant.

Allowable Values:

50 char max
network

string

Required		Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, DISCOVER, PULSE
sub_network

string

Optional		Indicates which subnetwork was used to complete the transaction.

NOTE: This field is called sub_network in the request, but is returned in the response as subnetwork.

Allowable Values:

- VISANET – Used for VisaNet signature-based transactions.
- VISANETDEBIT – Used for VisaNet Debit PIN-based transaction.
- VISAINTERLINK – Used for Visa Interlink PIN-based transactions.
- VISAPLUS – Used for ATM withdrawals on Visa.
- MAESTRO – Used for PIN-based transactions on Mastercard.
- CIRRUS – Used for ATM withdrawals on Mastercard.
- MASTERCARDDEBIT – Used for signature-based transactions on Mastercard.
network_fees

array of objects

Optional		Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.
local_amount

number

Optional		Amount paid in the currency used to complete the transaction.

Allowable Values:

Format: 0.00
local_currency

string

Optional		Currency code for the country where the transaction took place.

Allowable Values:

ISO 4217 currency codes, either alphabetic or numeric
currency_conversion_rate

number

Optional		Ratio between the amount the payee receives in their local currency, and the amount the cardholder pays in the currency of their account. Should be defined for multi-currency transactions.

Allowable Values:

Greater than zero.
settlement_currency

string

Optional		Currency code for the country where the transaction was settled. If not provided, the default currency is USD.

Allowable Values:

ISO 4217 currency codes, either alphabetic or numeric
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

FieldsDescription
type

string

Optional		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.
- CROSS_BORDER_CARDHOLDER_FEE – Cross-border fee charged to the cardholder by the card network. Impacts 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
CROSS_BORDER_CARDHOLDER_FEE / D

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body (create authorization)

Endpoint: /simulate/advanced/transactions
JSON
{
  "card_token": "9693eb07-2e81-4967-8d80-13d7e92aaafa",
  "mid": "11111",
  "amount": 20,
  "network": "VISA"
}

​
Sample response body (create authorization)

JSON
{
  "transaction": {
    "type": "authorization",
    "state": "PENDING",
    "identifier": "95",
    "token": "dfc41985-974b-46c1-b45a-412f5487799b",
    "user_token": "3fe0c221-b75c-4451-b12c-535abbfb1fe8",
    "acting_user_token": "3fe0c221-b75c-4451-b12c-535abbfb1fe8",
    "card_token": "9693eb07-2e81-4967-8d80-13d7e92aaafa",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 250,
      "available_balance": 145,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -20,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 250,
          "available_balance": 145,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -20
        }
      }
    },
    "duration": 190,
    "created_time": "2021-04-08T20:06:03Z",
    "user_transaction_time": "2021-04-08T20:06:03Z",
    "settlement_date": "2021-04-08T00:00:00Z",
    "request_amount": 20,
    "amount": 20,
    "currency_conversion": {
      "network": {
        "original_amount": 20,
        "conversion_rate": 1,
        "original_currency_code": "840"
      }
    },
    "currency_code": "USD",
    "approval_code": "521102",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "institution_country": "840",
      "institution_id_code": "103225153",
      "retrieval_reference_number": "397893807403",
      "system_trace_audit_number": "931011"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "6893",
      "metadata": {}
    },
    "card_security_code_verification": {
      "type": "CVV1",
      "response": {
        "code": "0000",
        "memo": "Card security code match"
      }
    },
    "fraud": {
      "network": {
        "transaction_risk_score": 97,
        "account_risk_score": "4 "
      }
    },
    "cardholder_authentication_data": {
      "verification_result": "not_present"
    },
    "issuer_received_time": "2021-04-08T20:06:03.404Z",
    "issuer_payment_node": "ce6af4a30b52e166c2257d65387191f2",
    "network_reference_id": "0002000430534031632",
    "acquirer_reference_data": "103225153",
    "card_acceptor": {
      "mid": "000000000011111",
      "mcc": "6411",
      "network_mid": "000000000011111",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "city": "St. Petersburg",
      "country": "USA",
      "poi": {
        "tid": "TR100000",
        "partial_approval_capable": "0",
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "processing_type": "MAGSTRIPE",
        "pin_present": "false"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Sample request body (increment authorization)

Endpoint: /simulate/advanced/authorization/incremental
JSON
{
  "card_token": "9693eb07-2e81-4967-8d80-13d7e92aaafa",
  "amount": 10,
  "network_reference_id": "0002000557129467263",
  "merchant_id": "11111",
  "network": "VISA",
  "sub_network": "VISANET"
}

​
Sample response body (increment authorization)

JSON
{
  "transaction": {
    "type": "authorization.incremental",
    "state": "PENDING",
    "identifier": "96",
    "token": "913fff78-ec73-440b-945c-1c2d4b8c3240",
    "user_token": "3fe0c221-b75c-4451-b12c-535abbfb1fe8",
    "acting_user_token": "3fe0c221-b75c-4451-b12c-535abbfb1fe8",
    "card_token": "9693eb07-2e81-4967-8d80-13d7e92aaafa",
    "preceding_related_transaction_token": "dfc41985-974b-46c1-b45a-412f5487799b",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 250,
      "available_balance": 135,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -10,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 250,
          "available_balance": 135,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -10
        }
      }
    },
    "duration": 114,
    "created_time": "2021-04-08T20:06:05Z",
    "user_transaction_time": "2021-04-08T20:06:05Z",
    "settlement_date": "2021-04-08T00:00:00Z",
    "request_amount": 10,
    "amount": 10,
    "currency_conversion": {
      "network": {
        "original_amount": 10,
        "conversion_rate": 1,
        "original_currency_code": "840"
      }
    },
    "currency_code": "USD",
    "approval_code": "556055",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "institution_country": "840",
      "institution_id_code": "901673712",
      "retrieval_reference_number": "251553478056",
      "system_trace_audit_number": "623128"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "6893",
      "metadata": {}
    },
    "card_security_code_verification": {
      "type": "CVV1",
      "response": {
        "code": "0000",
        "memo": "Card security code match"
      }
    },
    "cardholder_authentication_data": {
      "verification_result": "not_present"
    },
    "issuer_received_time": "2021-04-08T20:06:05.372Z",
    "issuer_payment_node": "ce6af4a30b52e166c2257d65387191f2",
    "network_reference_id": "0002000430534031632",
    "acquirer_reference_data": "901673712",
    "card_acceptor": {
      "mid": "000000000011111",
      "mcc": "6411",
      "network_mid": "000000000011111",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "city": "St. Petersburg",
      "country": "USA",
      "poi": {
        "tid": "TR100000",
        "partial_approval_capable": "0",
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "processing_type": "MAGSTRIPE",
        "pin_present": "false"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Simulate PIN-Debit Authorization Transactions

Simulate PIN-debit authorization and clearing transactions. The typical use case 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. For this use case, you use two endpoints: one to create the authorization and another to clear it.
  • Create the authorization using the /simulate/advanced/pindebit/authorization endpoint:
    Action: POST
    Endpoint: /simulate/advanced/pindebit/authorization
  • Clear the authorization using the /simulate/financial/advice endpoint:
    Action: POST
    Endpoint: /simulate/financial/advice

​
Body field details (create authorization)

FieldsDescription
card_token

string

Required		The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token.
amount

number

Required		The amount of the transaction.

Allowable Values:

Format: 0.00
merchant_id

string

Required		Merchant ID. The unique identification number of a merchant.

Allowable Values:

50 char max
network

string

Required		Indicates which card network was used to complete the transaction.

Allowable Values:

VISA, MASTERCARD, DISCOVER, PULSE
webhook

object

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

Allowable Values:

A valid webhook object.

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body (create authorization)

Endpoint: /simulate/advanced/pindebit/authorization
JSON
{
  "card_token": "84da2553-c7bc-4658-a824-bd5c425e14a9",
  "amount": 100.00,
  "merchant_id": "11111",
  "network": "VISA"
}

​
Sample response body (create authorization)

JSON
{
  "transaction": {
    "type": "pindebit.authorization",
    "state": "PENDING",
    "identifier": "4814",
    "token": "7de8495d-acb7-4c77-8956-098d0a0fced5",
    "user_token": "462b3a6e-0aa4-480a-aeeb-2aec175ecad7",
    "acting_user_token": "462b3a6e-0aa4-480a-aeeb-2aec175ecad7",
    "card_token": "84da2553-c7bc-4658-a824-bd5c425e14a9",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 999740.00,
      "available_balance": 998687.00,
      "credit_balance": 0.00,
      "pending_credits": 0.00,
      "impacted_amount": -100.00,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 999740.00,
          "available_balance": 998687.00,
          "credit_balance": 0.00,
          "pending_credits": 0.00,
          "impacted_amount": -100.00
        }
      }
    },
    "duration": 393,
    "created_time": "2021-06-08T19:06:38Z",
    "user_transaction_time": "2021-06-08T19:06:38Z",
    "settlement_date": "2021-06-08T00:00:00Z",
    "request_amount": 100.00,
    "amount": 100.00,
    "currency_conversion": {
      "network": {
        "original_amount": 100.00,
        "conversion_rate": 1.0,
        "original_currency_code": "840"
      }
    },
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "740409",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "institution_country": "840",
      "institution_id_code": "024392439",
      "retrieval_reference_number": "410677066167",
      "system_trace_audit_number": "536649"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "1749",
      "metadata": {}
    },
    "card_security_code_verification": {
      "type": "CVV1",
      "response": {
        "code": "0000",
        "memo": "Card security code match"
      }
    },
    "fraud": {
      "network": {
        "transaction_risk_score": 61,
        "account_risk_score": "3 "
      }
    },
    "cardholder_authentication_data": {
      "verification_result": "not_present"
    },
    "issuer_received_time": "2021-06-08T19:06:38.684Z",
    "issuer_payment_node": "f8205a67b12b90d695b15704a64c074b",
    "network_reference_id": "0002000235253627941",
    "acquirer_reference_data": "024392439",
    "card_acceptor": {
      "mid": "000000000011111",
      "mcc": "5542",
      "network_mid": "000000000011111",
      "mcc_groups": [
        "d49597f4-08ef-11e7-89fb-234d1996a57b"
      ],
      "name": "Marqeta Storefront",
      "city": "St. Petersburg",
      "country": "USA",
      "poi": {
        "tid": "TR100000",
        "partial_approval_capable": "0",
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "processing_type": "MAGSTRIPE",
        "pin_present": "false"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Body field details (clear authorization)

FieldsDescription
original_transaction_token

string

Required		The unique identifier of the original transaction.

Allowable Values:

Existing transaction token.
amount

number

Required		The amount of the transaction.

Allowable Values:

Format: 0.00
webhook

object

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

Allowable Values:

A valid webhook object.

​
Sample request body (clear authorization)

Endpoint: /simulate/financial/advice
JSON
{
  "original_transaction_token": "7de8495d-acb7-4c77-8956-098d0a0fced5",
  "amount": 30.00
}

​
Sample response body (clear authorization)

JSON
{
  "transaction": {
    "type": "pindebit.authorization.clearing",
    "state": "COMPLETION",
    "identifier": "4815",
    "token": "b90a00c1-71d9-484a-8670-844a1f2173ff",
    "user_token": "462b3a6e-0aa4-480a-aeeb-2aec175ecad7",
    "acting_user_token": "462b3a6e-0aa4-480a-aeeb-2aec175ecad7",
    "card_token": "84da2553-c7bc-4658-a824-bd5c425e14a9",
    "preceding_related_transaction_token": "7de8495d-acb7-4c77-8956-098d0a0fced5",
    "preceding_transaction": {
      "amount": 100.00,
      "token": "7de8495d-acb7-4c77-8956-098d0a0fced5"
    },
    "amount_to_be_released": 70.00,
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 999710.00,
      "available_balance": 998757.00,
      "credit_balance": 0.00,
      "pending_credits": 0.00,
      "impacted_amount": -30.00,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 999710.00,
          "available_balance": 998757.00,
          "credit_balance": 0.00,
          "pending_credits": 0.00,
          "impacted_amount": -30.00
        }
      }
    },
    "duration": 242,
    "created_time": "2021-06-08T19:06:48Z",
    "user_transaction_time": "2021-06-08T19:06:38Z",
    "request_amount": 30.00,
    "amount": 30.00,
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "740409",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "institution_id_code": "000000",
      "system_trace_audit_number": "674397"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "1749",
      "metadata": {}
    },
    "issuer_received_time": "2021-06-08T19:06:48.584Z",
    "issuer_payment_node": "f8205a67b12b90d695b15704a64c074b",
    "network_reference_id": "0002000235253627941",
    "acquirer_reference_data": "024392439",
    "card_acceptor": {
      "mid": "000000000011111",
      "mcc": "5542",
      "network_mid": "000000000011111",
      "mcc_groups": [
        "d49597f4-08ef-11e7-89fb-234d1996a57b"
      ],
      "name": "Marqeta Storefront",
      "city": "St. Petersburg",
      "country": "USA",
      "poi": {
        "partial_approval_capable": "0"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Reverse ATM transactions

Simulate reversing ATM and PIN-debit transactions. A reversal releases the hold that was placed on account funds by an authorization and returns the funds to the account. For this use case, you use two endpoints: one to create the transaction and another to reverse and refund the transaction.
  • Create the transaction using the /simulate/advanced endpoint:
    Action: POST
    Endpoint: /simulate/advanced/authorization
  • Reverse the transaction using the public /simulate endpoint:
    Action: POST
    Endpoint: /simulate/reversal

​
Body field details (create transaction)

FieldsDescription
mid

string

Optional		Merchant ID. The unique identification number of a merchant.

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

Conditionally required		The PIN number for the associated card.

Required when the transaction involves a PIN-protected account. This requirement may be set at the program level.

Allowable Values:

4 char max
amount

number

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

array of objects

Optional		Simulates various types of fees levied on the transaction.

Allowable Values:

A valid array of network_fees objects.
mti

string

Required		ISO 8583 message type indicator.

Allowable Values:

- 0100 for dual-message transactions
- 0200 for single-message transactions such as ATM withdrawals
processing_code

string

Conditionally required		Internal Marqeta field.

Required when the value of mti is 0200.

Allowable Values:

01
rrn

string

Optional		The Retrieval Reference Number.

Allowable Values:

01
stan

string

Optional		The Systems Trace Audit Number.

Allowable Values:

Must be 6 digits.
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

FieldsDescription
mcc

string

Optional		Merchant category code.

Allowable Values:

5 char max
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

​
The network_fees object

FieldsDescription
type

string

Optional		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.
- CROSS_BORDER_CARDHOLDER_FEE – Cross-border fee charged to the cardholder by the card network. Impacts 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
CROSS_BORDER_CARDHOLDER_FEE / D

​
The webhook object

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

Marqeta does not impose specific requirements for this password.

​
Sample request body (create transaction)

Endpoint: /simulate/advanced/authorization
JSON
{
  "amount": 21,
  "cash_back_amount": 20,
  "card_token": "cb80e186-1c4a-482c-9460-197ce44aafea",
  "mid": "1234",
  "pin": "2641",
  "network": "VISA",
  "mti": "0200",
  "processing_code": "09",
  "pos_pan_entry_mode": "MAG_STRIPE",
  "rrn": 9538147919,
  "stan": "204154",
  "network_fees": [
    {
      "type": "PINDEBIT_ASSOC_FEE",
      "amount": 1,
      "credit_debit": "D"
    }
  ]
}

​
Sample response body (create transaction)

JSON
{
  "transaction": {
    "type": "pindebit.cashback",
    "state": "COMPLETION",
    "identifier": "435",
    "token": "734df617-3aa3-4eeb-8101-3ec3228e4346",
    "user_token": "216a00b3-596f-4ef1-9694-78e6191f8171",
    "acting_user_token": "216a00b3-596f-4ef1-9694-78e6191f8171",
    "card_token": "cb80e186-1c4a-482c-9460-197ce44aafea",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 978,
      "available_balance": 978,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": -22,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 978,
          "available_balance": 978,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": -22
        }
      }
    },
    "duration": 413,
    "created_time": "2020-10-15T22:21:05Z",
    "user_transaction_time": "2020-10-15T22:21:05Z",
    "settlement_date": "2020-10-15T00:00:00Z",
    "request_amount": 22,
    "cash_back_amount": 20,
    "amount": 21,
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "828527",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 1,
    "acquirer": {
      "retrieval_reference_number": "9538147919",
      "system_trace_audit_number": "204154"
    },
    "fees": [
      {
        "type": "PINDEBIT_ASSOC_FEE",
        "amount": 1,
        "credit_debit": "D"
      }
    ],
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "4819",
      "metadata": {}
    },
    "issuer_received_time": "2020-10-15T22:21:05.966Z",
    "issuer_payment_node": "ce6af4a30b52e166c2257d65387191f2",
    "network_reference_id": "858000023489",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA",
      "poi": {
      "cardholder_presence": "0",
      "card_presence": "0",
      "channel": "OTHER",
      "pin_present": "true"
      }
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Body field details (reverse transaction)

See Simulate reversal in Simulating Transactions.

​
Sample request body (reverse transaction)

Endpoint: /simulate/reversal
JSON
{
  "original_transaction_token": "734df617-3aa3-4eeb-8101-3ec3228e4346",
  "amount": 21
}

​
Sample response body (reverse transaction)

JSON
{
  "transaction": {
    "type": "pindebit.reversal",
    "state": "COMPLETION",
    "identifier": "436",
    "token": "a947fa99-6491-4db5-a7e7-373a6acb9f06",
    "user_token": "216a00b3-596f-4ef1-9694-78e6191f8171",
    "acting_user_token": "216a00b3-596f-4ef1-9694-78e6191f8171",
    "card_token": "cb80e186-1c4a-482c-9460-197ce44aafea",
    "preceding_related_transaction_token": "734df617-3aa3-4eeb-8101-3ec3228e4346",
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 999,
      "available_balance": 999,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": 21,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 999,
          "available_balance": 999,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": 21
        }
      }
    },
    "duration": 195,
    "created_time": "2020-10-15T22:21:07Z",
    "user_transaction_time": "2020-10-15T22:21:05Z",
    "settlement_date": "2020-10-15T00:00:00Z",
    "request_amount": 22,
    "amount": 21,
    "currency_code": "USD",
    "approval_code": "828527",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "system_trace_audit_number": "204154"
    },
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "4819",
      "metadata": {}
    },
    "issuer_received_time": "2020-10-15T22:21:07.013Z",
    "issuer_payment_node": "ce6af4a30b52e166c2257d65387191f2",
    "network_reference_id": "858000023489",
    "card_acceptor": {
      "mid": "1234",
      "mcc": "6411",
      "network_mid": "1234",
      "mcc_groups": [
        "NONE"
      ],
      "name": "Marqeta Storefront",
      "address": "330 Central Ave.",
      "city": "St. Petersburg",
      "state": "FL",
      "zip": "33705",
      "country": "USA"
    },
    "is_recurring": false,
    "is_installment": false
  }
}

​
Get a list of transactions as a batch

Request transactions using the instructions provided for the GET /transactions endpoint of the Transactions page. To subscribe to webhooks for transactions, see Step 2 — Subscribe to event notifications in the Tutorial section of About Webhooks.

Related topics

Simulating TransactionsTransactionsAbout TransactionsTransactions OverviewTransaction Processing in Europe