Simulating Transactions

We are planning to deprecate these endpoints in the future. Please consider updating your tests to use Simulations 2.0 as soon as possible. If you are new to Marqeta’s Simulations service, start testing your integration using the recently released Simulations 2.0 API for card transactions and direct deposits. If you are currently using the Simulations service described on this page, consider switching to the Simulations 2.0 service. The Simulations 2.0 service includes all the capabilities of the previous versions of Simulations, plus it offers a new set of endpoints and a Postman collection. 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

Action: POST
Endpoint: /simulate/authorization Simulate an authorization type transaction by including the card_token and other authorization details in your request.

Body field details

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

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

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

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

Fields	Description
additional_data string Optional	Additional information about the transaction. Allowable Values: 255 char max

The network_fees object

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

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

JSON

{
  "amount": "10.00",
  "mid": "11111",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "transaction_options": {
    "additional_data": "my_additional data"
  },
  "card_acceptor": {
    "name": "Aegis Fleet Services",
    "address": "111 Main St",
    "city": "Berkeley",
    "state": "CA",
    "zip": "94702"
  },
  "webhook": {
    "endpoint": "https://mysecuredomain.com",
    "username": "my_username",
    "password": "My_passw0rd"
  }
}

Sample response body

JSON

{
  "type": "authorization",
  "state": "PENDING",
  "token": "9cbbdb91-81bb-4d26-acea-2734a67a96d2",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 20,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -10,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 20,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -10
      }
    }
  },
  "gpa_order": {
    "token": "3f55f689-7622-4660-9ce9-209a9e6b1a5a",
    "amount": 10,
    "created_time": "2024-07-11T16:30:00Z",
    "last_modified_time": "2024-07-11T16:30:00Z",
    "transaction_token": "e8fdd8d3-cc41-4cd6-9df0-e1071993c633",
    "state": "PENDING",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 10,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-07-10T00:09:35Z",
        "last_modified_time": "2024-07-10T00:09:35Z"
      }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 202,
  "created_time": "2024-07-11T16:30:00Z",
  "user_transaction_time": "2024-07-11T16:30:00Z",
  "settlement_date": "2024-07-11T00:00:00Z",
  "request_amount": 10,
  "amount": 10,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "015382",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0,
  "acquirer": {
    "system_trace_audit_number": "049258"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Aegis Fleet Services",
    "street_address": "111 Main St",
    "city": "Berkeley",
    "state": "CA",
    "zip": "94702",
    "country_code": "USA"
  },
  "pos": {
    "partial_approval_capable": true,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate authorization advice

Action: POST
Endpoint: /simulate/authorization/advice 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

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

Fields	Description
additional_data string Optional	Additional information about the transaction. Allowable Values: 255 char max

The network_fees object

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

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

JSON

{
  "amount": "1.00",
  "original_transaction_token": "9cbbdb91-81bb-4d26-acea-2734a67a96d2"
}

Sample response body

JSON

{
  "type": "authorization.advice",
  "state": "PENDING",
  "token": "78e61ee3-f811-49b0-ab58-1f485d353b3z",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "preceding_related_transaction_token": "9cbbdb91-81bb-4d26-acea-2734a67a96d2",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 11,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -1,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 11,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -1
      }
    }
  },
  "gpa_order": {
    "token": "3f55f689-7622-4660-9ce9-209a9e6b1a5a",
    "amount": 9,
    "created_time": "2024-07-11T16:30:00Z",
    "last_modified_time": "2024-07-11T16:32:42Z",
    "transaction_token": "913ad4fe-dfec-46af-ae0f-dda84c90edd6",
    "state": "PENDING",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 9,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-07-10T00:09:35Z",
        "last_modified_time": "2024-07-10T00:09:35Z"
      }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 198,
  "created_time": "2024-07-11T16:32:42Z",
  "user_transaction_time": "2024-07-11T16:30:00Z",
  "settlement_date": "2024-07-11T00:00:00Z",
  "request_amount": 1,
  "amount": 1,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "015382",
  "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": "000001"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Aegis Fleet Services",
    "street_address": "111 Main St",
    "city": "Berkeley",
    "state": "CA",
    "zip": "94702",
    "country_code": "USA"
  },
  "pos": {
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate clearing or refund

Action: POST
Endpoint: /simulate/clearing 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

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

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

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

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

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

JSON

{
  "amount": "2.00",
  "original_transaction_token": "78e61ee3-f811-49b0-ab58-1f485d353b3z"
}

Send the following request to simulate a refund type transaction.

JSON

{
  "amount": "2.00",
  "original_transaction_token": "ebc1aa7d-0d9d-4205-b963-64693364e52d",
  "is_refund": true
}

Sample response body

The following response shows an authorization.clearing type transaction.

JSON

{
  "type": "authorization.clearing",
  "state": "COMPLETION",
  "token": "2b7e3730-92e8-49dc-91c3-10a9186b79d1",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "preceding_related_transaction_token": "78e61ee3-f811-49b0-ab58-1f485d353b3z",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 10,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -2,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -2
      }
    }
  },
  "gpa_order": {
   "token": "3f55f689-7622-4660-9ce9-209a9e6b1a5a",
    "amount": 2,
    "created_time": "2024-07-11T16:30:00Z",
    "last_modified_time": "2024-07-11T16:35:56Z",
    "transaction_token": "1037",
    "state": "COMPLETION",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 2,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-07-10T00:09:35Z",
        "last_modified_time": "2024-07-10T00:09:35Z"
      }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 196,
  "created_time": "2024-07-11T16:35:56Z",
  "user_transaction_time": "2024-07-11T16:30:00Z",
  "settlement_date": "2024-07-11T00:00:00Z",
  "request_amount": 2,
  "amount": 2,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "015382",
  "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": "000002"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Aegis Fleet Services",
    "street_address": "111 Main St",
    "city": "Berkeley",
    "state": "CA",
    "zip": "94702",
    "country_code": "USA"
  },
    "pos": {
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

The following response shows a refund type transaction.

JSON

{
  "type": "refund",
  "state": "COMPLETION",
  "token": "8318385b-e1f5-4139-a289-0036d1e4fd3b",
  "user_token": "25380999-767d-4251-9270-9d1343217694",
  "acting_user_token": "25380999-767d-4251-9270-9d1343217694",
  "card_token": "98bf1581-7cfb-4184-992f-586d6a1d0eec",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 20,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": 2,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 20,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 2
      }
    }
  },
  "duration": 150,
  "created_time": "2024-02-12T22:32:25Z",
  "user_transaction_time": "2024-02-12T22:32:25Z",
  "settlement_date": "2024-02-12T00:00:00Z",
  "request_amount": 2,
  "amount": 2,
  "currency_code": "USD",
  "approval_code": "536048",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "gpa_order_unload": {
    "token": "2c6af635-0c71-43bb-a1c8-94d0143e3d6c",
    "amount": 2,
    "created_time": "2024-02-12T22:32:25Z",
    "last_modified_time": "2024-02-12T22:32:26Z",
    "transaction_token": "11ad414a-2678-4d91-aef1-a10d3b08da64",
    "state": "COMPLETION",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 2,
      "source": {
        "type": "program",
        "token": "**********6b51",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-01-28T19:20:33Z",
        "last_modified_time": "2024-01-28T19:20:33Z"
      }
    },
    "funding_source_token": "**********6b51"
  },
  "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0,
  "acquirer": {
    "institution_id_code": "000000",
    "system_trace_audit_number": "000005"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Marqeta Storefront",
    "street_address": "330 Central Ave.",
    "city": "St. Petersburg",
    "state": "FL",
    "zip": "33705",
    "country_code": "USA"
  },
  "pos": {
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate financial

Action: POST
Endpoint: /simulate/financial 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

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

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

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

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

JSON

{
  "amount": "2.50",
  "mid": "11111",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "is_pre_auth": false
}

Sample response body

JSON

{
  "type": "pindebit",
  "state": "COMPLETION",
  "token": "0ae44166-058d-4882-b39f-13fea8c6e387",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 10,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -2.5,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -2.5
      }
    }
  },
  "gpa_order": {
    "token": "ed059525-d7ee-4156-a5ff-d57e65d1eae9",
    "amount": 2.5,
    "created_time": "2024-07-11T16:37:50Z",
    "last_modified_time": "2024-07-11T16:37:50Z",
    "transaction_token": "49cb176b-9d8b-4fbc-8b22-45b83d15d7c9",
    "state": "COMPLETION",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 2.5,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-07-10T00:09:35Z",
        "last_modified_time": "2024-07-10T00:09:35Z"
      }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 166,
  "created_time": "2024-07-11T16:37:50Z",
  "user_transaction_time": "2024-07-11T16:37:50Z",
  "request_amount": 2.5,
  "amount": 2.5,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "328310",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0,
  "acquirer": {
    "institution_id_code": "34483739464",
    "retrieval_reference_number": "088404447069",
    "system_trace_audit_number": "621801"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Marqeta Storefront",
    "street_address": "330 Central Ave.",
    "city": "St. Petersburg",
    "state": "FL",
    "zip": "33705",
    "country_code": "USA"
  },
  "pos": {
    "terminal_id": "TR100000",
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate financial advice

Action: POST
Endpoint: /simulate/financial/advice 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

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

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

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

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

JSON

{
  "amount": "1.00",
  "original_transaction_token": "0ae44166-058d-4882-b39f-13fea8c6e387"
}

Sample response body

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

JSON

{
  "type": "pindebit.authorization.clearing",
  "state": "COMPLETION",
  "token": "78382109-7dbe-4bf9-9f0c-88ffba67288a",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "preceding_related_transaction_token": "0ae44166-058d-4882-b39f-13fea8c6e387",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 10,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": 1.5,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 1.5
      }
    }
  },
  "gpa_order": {
    "token": "3a5c0005-1d66-4ed0-9b70-57229ae6a7d8",
    "amount": 1,
    "created_time": "2024-07-11T16:37:50Z",
    "last_modified_time": "2024-07-11T16:39:38Z",
    "transaction_token": "78382109-7dbe-4bf9-9f0c-88ffba67288a",
    "state": "COMPLETION",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 1,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-07-10T00:09:35Z",
        "last_modified_time": "2024-07-10T00:09:35Z"
        }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 167,
  "created_time": "2024-07-11T16:39:38Z",
  "user_transaction_time": "2024-07-11T16:37:50Z",
  "request_amount": 1,
  "amount": 1,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "328310",
  "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": "767425"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "00",
    "name": "Marqeta Storefront",
    "street_address": "330 Central Ave.",
    "city": "St. Petersburg",
    "state": "FL",
    "zip": "33705",
    "country_code": "USA"
  },
  "pos": {
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate balance inquiry

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

Body field details

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

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

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

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

JSON

{
  "mid": "11111",
  "account_type": "savings",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb"
}

Sample response body

JSON

{
  "type": "pindebit.balanceinquiry",
  "state": "CLEARED",
  "token": "d6a4693d-60b3-461b-b048-212ad923a7ed",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "4abf0fe1-2470-4cc8-b83e-c7db9a59bcdb",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 10,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0
      }
    }
  },
  "duration": 41,
  "created_time": "2024-07-11T16:41:56Z",
  "user_transaction_time": "2024-07-11T16:41:56Z",
  "request_amount": 0,
  "amount": 0,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "147041",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0,
  "acquirer": {
    "institution_id_code": "86285207437",
    "retrieval_reference_number": "775498102690",
    "system_trace_audit_number": "637714"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Marqeta Storefront",
    "street_address": "330 Central Ave.",
    "city": "St. Petersburg",
    "state": "FL",
    "zip": "33705",
    "country_code": "USA"
  },
  "pos": {
    "terminal_id": "TR100000",
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate ATM withdrawal

Action: POST
Endpoint: /simulate/financial/withdrawal Simulate a pindebit.atm.withdrawal type transaction by including the card_token and amount in your request.

Body field details

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

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

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

JSON

{
  "mid": "11111",
  "account_type": "savings",
  "card_token": "f9c00b07-be2d-4240-ad89-98a0595fc3a2",
  "amount": "1.00"
}

Sample response body

JSON

{
  "type": "pindebit.atm.withdrawal",
  "state": "COMPLETION",
  "token": "d566329d-4886-4170-a42a-337deb1acaa2",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "f9c00b07-be2d-4240-ad89-98a0595fc3a2",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 10,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -1,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -1
      }
    }
  },
  "gpa_order": {
    "token": "d5f0486a-e831-4926-9e59-47427948d68d",
    "amount": 1,
    "created_time": "2024-07-11T19:45:22Z",
    "last_modified_time": "2024-07-11T19:45:22Z",
    "transaction_token": "a870af0e-f98e-40d3-a8d2-350d015d69f9",
    "state": "COMPLETION",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding": {
      "amount": 1,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
        "is_default_account": false,
        "created_time": "2024-07-10T00:09:35Z",
        "last_modified_time": "2024-07-10T00:09:35Z"
      }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 129,
  "created_time": "2024-07-11T19:45:22Z",
  "user_transaction_time": "2024-07-11T19:45:22Z",
  "request_amount": 1,
  "amount": 1,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "693945",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0,
  "acquirer": {
    "institution_id_code": "59103660914",
    "retrieval_reference_number": "492752528413",
    "system_trace_audit_number": "977404"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Marqeta Storefront",
    "street_address": "330 Central Ave.",
    "city": "St. Petersburg",
    "state": "FL",
    "zip": "33705",
    "country_code": "USA"
  },
  "pos": {
    "terminal_id": "TR100000",
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate reversal

Action: POST
Endpoint: /simulate/reversal 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

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

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

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

JSON

{
  "amount": "10.00",
  "original_transaction_token": "94c97e14-7915-4806-a609-dbb02c35c413"
}

Sample response body

JSON

{
  "type": "authorization.reversal",
  "state": "CLEARED",
  "token": "1049",
  "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "acting_user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
  "card_token": "f9c00b07-be2d-4240-ad89-98a0595fc3a2",
  "preceding_related_transaction_token": "210e81f1-9604-4c47-b28c-8c436740014e",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 10,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": 10,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 10
      }
    }
  },
  "gpa_order": {
    "token": "d2cb5eb3-6d76-4d82-b5e1-85d948cde9f0",
    "amount": 10,
    "created_time": "2024-07-11T19:48:08Z",
    "last_modified_time": "2024-07-11T19:48:33Z",
    "transaction_token": "c4a491a3-284e-45c6-81db-0e9d1e6c7e72",
    "state": "REVERSED",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
  },
    "funding": {
      "amount": 10,
      "source": {
        "type": "program",
        "token": "**********b4c2",
        "active": true,
        "name": "PFS for simulating transactions",
         "is_default_account": false,
         "created_time": "2024-07-10T00:09:35Z",
         "last_modified_time": "2024-07-10T00:09:35Z"
      }
    },
    "funding_source_token": "**********b4c2",
    "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
    "currency_code": "USD"
  },
  "duration": 113,
  "created_time": "2024-07-11T19:48:33Z",
  "user_transaction_time": "2024-07-11T19:48:08Z",
  "request_amount": 10,
  "amount": 10,
  "issuer_interchange_amount": 0,
  "currency_code": "USD",
  "approval_code": "593222",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
 "network": "VISA",
  "subnetwork": "VISANET",
  "acquirer_fee_amount": 0,
  "acquirer": {
    "system_trace_audit_number": "199288"
  },
  "user": {
    "metadata": {}
  },
  "card": {
    "metadata": {}
  },
  "card_acceptor": {
    "mid": "11111",
    "mcc": "6411",
    "name": "Aegis Fleet Services",
    "street_address": "111 Main St",
    "city": "Berkeley",
    "state": "CA",
    "zip": "94702",
    "country_code": "USA"
  },
  "pos": {
    "partial_approval_capable": false,
    "purchase_amount_only": false,
    "is_recurring": false
  }
}

Simulate ACH Receiving

Action: POST
Endpoint: /simulate/directdeposits 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 ACH Receiving. 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

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/` 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

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

JSON

{
  "amount": 10,
  "type": "CREDIT",
  "account_number": "1323975092920",
  "settlement_date": "2024-03-23T19:56:53.440Z"
}

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

JSON

{
  "amount": 10,
  "type": "DEBIT",
  "account_number": "1323975092920",
  "settlement_date": "2024-03-23T19:56:53.440Z"
}

Sample responses

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

{
  "token": "a1aee855-0fe7-4a97-9c08-5c14d09f2478",
  "amount": 10,
  "type": "CREDIT",
  "state": "PENDING",
  "settlement_date": "2024-03-23T19:56:53Z",
  "state_reason": "Newly created",
  "direct_deposit_account_token": "4e7953ba-0be5-4a85-996f-e24d7763552f",
  "user_token": "506d8154-c01a-4480-81c9-04a0f4b451c1",
  "created_time": "2024-03-23T20:35:28Z",
  "last_modified_time": "2024-03-23T20:35:28Z"
}

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

{
  "token": "246e3441-adbd-4481-899c-e0a2a141c107",
  "amount": 5.0,
  "type": "DEBIT",
  "state": "PENDING",
  "settlement_date": "2024-03-12T19:56:53Z",
  "state_reason": "Newly created",
  "direct_deposit_account_token": "1741ad42-aac9-485a-8799-3c2edc2385f8",
  "user_token": "6252d4d8-d3e4-499b-a8dc-0c9bc2c351ca",
  "created_time": "2024-03-12T19:47:15Z",
  "last_modified_time": "2024-03-12T19:47:15Z"
}

Simulate OCT

Action: POST
Endpoint: /simulate/financial/originalcredit 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

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

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

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

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

Send the following request to simulate a disbursement type transaction.

JSON

{
  "amount": 10,
  "card_token": "ce2002fd-5e9a-4c9b-a82d-cc74da4e8280",
  "mid": "11111",
  "type": "disbursement"
}

Sample response body

The following response simulates a disbursement type transaction.

JSON

{
  "transaction": {
    "type": "original.credit.auth_plus_capture",
    "state": "COMPLETION",
    "token": "84f39ded-0700-41e5-911e-89215a77104c",
    "user_token": "fc7c4a77-f105-44b0-8424-f9f9c3d4d090",
    "acting_user_token": "fc7c4a77-f105-44b0-8424-f9f9c3d4d090",
    "card_token": "380e26fe-4f9f-4ee0-9fb8-e26062be8445",
    "original_credit": {
      "transaction_type": "disbursement"
    },
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 10,
      "available_balance": 10,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": 10,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 10,
          "available_balance": 10,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": 10
        }
      }
    },
    "duration": 199,
    "created_time": "2024-07-08T23:47:04Z",
    "user_transaction_time": "2024-07-08T23:47:04Z",
    "request_amount": 10,
    "amount": 10,
    "currency_code": "USD",
    "approval_code": "206645",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "merchant": {
      "name": "John Doe Merchant Inc.",
      "active": true,
      "contact": "John D. Doe",
      "contact_email": "jdoe@domain.com",
      "longitude": 0,
      "latitude": 0,
      "address1": "180 Grand Avenue",
      "address2": "Suite 2303",
      "city": "Oakland",
      "state": "CA",
      "zip": "94612",
      "country": "USA",
      "token": "c0b3f6cd-146e-45a8-9440-efcce623dd37",
      "partial_auth_flag": true,
      "created_time": "2024-02-14T00:57:02Z",
      "last_modified_time": "2024-02-14T00:57:02Z"
    },
    "store": {
      "name": "Aegis Fleet Services",
      "active": false,
      "longitude": 0,
      "latitude": 0,
      "address1": "111 Main St",
      "city": "Berkeley",
      "state": "CA",
      "zip": "94702",
      "token": "8f195870-94ce-4bfd-ac46-75a4fcf17500",
      "partial_auth_flag": true,
      "mid": "11111",
      "merchant_token": "c0b3f6cd-146e-45a8-9440-efcce623dd37",
      "partial_approval_capable": true,
      "keyed_auth_cvv_enforced": false,
      "created_time": "2024-02-14T01:18:38Z",
      "last_modified_time": "2024-02-14T01:18:38Z"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "institution_id_code": "05779900106",
      "retrieval_reference_number": "726213433770",
      "system_trace_audit_number": "881236"
    },
    "fees": [
      {
        "type": "ISSUER_LOAD_SURCHARGE_FEE",
        "amount": 0
      }
    ],
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "3201",
      "metadata": {}
    },
    "issuer_received_time": "2024-07-08T23:47:04.577Z",
    "issuer_payment_node": "715de90f8dd6eeb2d87251dd691d7de2",
    "card_acceptor": {
      "mid": "11111",
      "mcc": "00",
      "country_code": "USA"
    },
    "pos": {
      "terminal_id": "TR100000",
      "partial_approval_capable": false,
      "purchase_amount_only": false,
      "is_recurring": false
    }
  },
    "raw_iso8583": {
      "0": "2210",
      "2": "1111119311153201",
      "3": "260000",
      "4": 10,
      "5": 10,
      "7": "0708234704",
      "11": "881236",
      "12": "114704",
      "13": "0708",
      "14": "2307",
      "15": "0708",
      "17": "0708",
      "22": "10000000020000000100000001000000",
      "26": "00",
      "32": "05779900106",
      "33": "13747132476",
      "37": "726213433770",
      "38": "206645",
      "39": "0000",
      "41": "TR100000",
      "42": "11111",
      "43": {
        "7": "840"
      },
      "44": {
        "1": "Approved or completed successfully",
        "3": "00",
        "4": "Approved or completed successfully"
      },
      "48": "OCT        07012020",
      "50": "840",
      "54": "00028402C00000000100000018402C000000001000",
      "58": "00000000022",
      "59": "0000000",
      "63": "VISA",
      "112": {
        "101": "10.00",
        "102": "10.00",
        "103": "840"
      },
      "113": {
        "2": "106",
        "32": "VISANET",
        "35": "API",
        "42": "DISBURSEMENT",
        "46": "true"
      },
      "123": "123 Main St.           "
    }
}

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​Simulate authorization

​Body field details

​The card_options object

​The card_options.billing_address object

​The card_acceptor object

​The transaction_options object

​The network_fees object

​The webhook object

​Sample request body

​Sample response body

​Simulate authorization advice

​Body field details

​The transaction_options object

​The network_fees object

​The webhook object

​Sample request body

​Sample response body

​Simulate clearing or refund

​Body field details

​The card_acceptor object

​The network_fees object

​The webhook object

​Sample request body

​Sample response body

​Simulate financial

​Body field details

​The card_acceptor object

​The transaction_options object

​The webhook object

​Sample request body

​Sample response body

​Simulate financial advice

​Body field details

​The transaction_options object

​The network_fees object

​The webhook object

​Sample request body

​Sample response body

​Simulate balance inquiry

​Body field details

​The card_acceptor object

​The network_fees object

​The webhook object

​Sample request body

​Sample response body

​Simulate ATM withdrawal

​Body field details

​The card_acceptor object

​The webhook object

​Sample request body

​Sample response body

​Simulate reversal

​Body field details

​The network_fees object

​The webhook object

​Sample request body

​Sample response body

​Simulate ACH Receiving

​Body field details

Simulate authorization

Body field details

The card_options object

The card_options.billing_address object

The card_acceptor object

The transaction_options object

The network_fees object

The webhook object

Sample request body

Sample response body

Simulate authorization advice

Body field details

The transaction_options object

The network_fees object

The webhook object

Sample request body

Sample response body

Simulate clearing or refund

Body field details

The card_acceptor object

The network_fees object

The webhook object

Sample request body

Sample response body

Simulate financial

Body field details

The card_acceptor object

The transaction_options object

The webhook object

Sample request body

Sample response body

Simulate financial advice

Body field details

The transaction_options object

The network_fees object

The webhook object

Sample request body

Sample response body

Simulate balance inquiry

Body field details

The card_acceptor object

The network_fees object

The webhook object

Sample request body

Sample response body

Simulate ATM withdrawal

Body field details

The card_acceptor object

The webhook object

Sample request body

Sample response body

Simulate reversal

Body field details

The network_fees object

The webhook object

Sample request body

Sample response body

Simulate ACH Receiving

Body field details

Sample requests

Sample responses

Simulate OCT

Body field details

The card_acceptor object

The sender_data object

The webhook object

Sample request body

Sample response body