Simulate authorization

Action: POST
Endpoint: /simulate/authorization

An authorization puts a temporary hold on card funds. This endpoint allows you to simulate authorizations that would actually be initiated by merchants in a production environment. To simulate a transaction authorization, send a POST request to the /simulate/authorization endpoint and include the card_token and other authorization details in JSON format in the body of the request.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
card_token string Yes The unique identifier of the card involved in the transaction. 255 char max
amount decimal Yes The amount of the transaction. 0.00
mid string Yes The Merchant Identifier of the merchant participating in the transaction. 255 char max
is_pre_auth boolean No Set to true to mark the amount as an authorization only. true | false

Default: false
card_acceptor object No Contains attributes that describe the merchant.
card_options object No Contains attributes that govern card usage.
transaction_options object No Contains additional information about the transaction.
pin string No If the transaction involves a PIN-protected account, this is the PIN number. 4 char max
cashback_amount decimal No If the transaction simulates authorization for cash back, this is the cash amount. 0.00
network_fees array of objects No Simulates various types of fees levied on the transaction.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The card_options object

Name Type Required? Description Allowable Values
cvv string No The CVV2 number for the card. 4 char max
expiration string No The expiration date of the card. mmdd
billing_address object No Used for AVS (address verification system). The address-related fields in this object are verified against known values.
card_present boolean No True requires that the card be present for the transaction. true | false

Default: false

The card_options.billing_address object

Name Type Required? Description Allowable Values
first_name string No Card holder's first name. To pass AVS, must match the first name on record.
last_name string No Card holder's last name. To pass AVS, must match the last name on record.
address string No Card holder's street address. To pass AVS, must match the address on record.
zip string No Card holders seven-digit zip code. To pass AVS, must match the zip code on record.

The card_acceptor object

Name Type Required? Description Allowable Values
name string No Merchant name. 255 char max
address string No Merchant address. 255 char max
city string No Merchant city. 255 char max
state string No Merchant state. 2 char max
zip string No Merchant zip. 10 char max

The transaction_options object

Name Type Required? Description Allowable Values
additional_data string No Additional information about the transaction. 255 char max

The network_fees object

Name Type Required? Description Allowable Values
type string No 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 Marqeta. Does not impact account balance.
CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.
ISSUER_FEE |
SWITCH_FEE |
PINDEBIT_ASSOC_FEE |
ACQUIRER_FEE |
INTERCHANGE_FEE |
CUR_CONV_CARDHOLDER_FEE
amount decimal No Specifies the amount of the fee. 0.00 format
credit_\debit string No Specifies whether the fee credits or debits the account balance. 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

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

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

Sample response body

{
    "type": "authorization",
    "state": "PENDING",
    "token": "1032",
    "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": "2018-07-11T16:30:00Z",
        "last_modified_time": "2018-07-11T16:30:00Z",
        "transaction_token": "1033",
        "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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 202,
    "created_time": "2018-07-11T16:30:00Z",
    "user_transaction_time": "2018-07-11T16:30:00Z",
    "settlement_date": "2018-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": "Chicken Tooth Music",
        "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 or increased after the authorization. This endpoint allows you to simulate post-swipe adjustments. To simulate an authorization advice, send a POST request to the /simulate/authorization/advice endpoint and include the original_transaction_token and other authorization details in JSON format in the body of the request.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
amount decimal Yes The amount of the transaction. 0.00
original_transaction_token string Yes The unique token that identifies the original transaction. Existing transaction token
transaction_options object No Contains additional information about the transaction.
network_fees array of objects No Simulates various types of fees levied on the transaction.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The transaction_options object

Name Type Required? Description Allowable Values
additional_data string No Additional information about the transaction. 255 char max

The network_fees object

Name Type Required? Description Allowable Values
type string No 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 Marqeta. Does not impact account balance.
CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.
ISSUER_FEE |
SWITCH_FEE |
PINDEBIT_ASSOC_FEE |
ACQUIRER_FEE |
INTERCHANGE_FEE |
CUR_CONV_CARDHOLDER_FEE
amount decimal No Specifies the amount of the fee. 0.00 format
credit_\debit string No Specifies whether the fee credits or debits the account balance. 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

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

{
"amount": "1.00",
"original_transaction_token": "1032"
}

Sample response body

{
    "type": "authorization.advice",
    "state": "PENDING",
    "token": "1034",
    "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": "1032",
    "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": "2018-07-11T16:30:00Z",
        "last_modified_time": "2018-07-11T16:32:42Z",
        "transaction_token": "1035",
        "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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 198,
    "created_time": "2018-07-11T16:32:42Z",
    "user_transaction_time": "2018-07-11T16:30:00Z",
    "settlement_date": "2018-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": "Chicken Tooth Music",
        "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

A settlement captures the funds (makes the hold permanent) that were placed on hold by an authorization. To simulate a clearing transaction, send a POST request to the /simulate/clearing endpoint and include the original_transaction_token and amount in JSON format in the body of the request. To simulate a refund, set the is_refund field.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
original_transaction_token string Yes The unique identifier of the transaction to clear. Existing transaction token
amount decimal Yes The amount of the transaction. 0.00
force_post boolean No 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).
true | false

Default: false
is_refund boolean No Set to true to simulate a refund transaction. true | false

Default: false
mid string No Merchant Identification number. 255 char max
card_acceptor object No Contains attributes that describe the merchant.
network_fees array of objects No Simulates various types of fees levied on the transaction.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The card_acceptor object

Name Type Required? Description Allowable Values
name string No Merchant name. 255 char max
address string No Merchant address. 255 char max
city string No Merchant city. 255 char max
state string No Merchant state. 2 char max
zip string No Merchant zip. 10 char max

The network_fees object

Name Type Required? Description Allowable Values
type string No 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 Marqeta. Does not impact account balance.
CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.
ISSUER_FEE |
SWITCH_FEE |
PINDEBIT_ASSOC_FEE |
ACQUIRER_FEE |
INTERCHANGE_FEE |
CUR_CONV_CARDHOLDER_FEE
amount decimal No Specifies the amount of the fee. 0.00 format
credit_\debit string No Specifies whether the fee credits or debits the account balance. 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

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

{
"amount": "2.00",
"original_transaction_token": "1034"
}

Sample response body

{
    "type": "authorization.clearing",
    "state": "COMPLETION",
    "token": "1036",
    "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": "1034",
    "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": "2018-07-11T16:30:00Z",
        "last_modified_time": "2018-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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 196,
    "created_time": "2018-07-11T16:35:56Z",
    "user_transaction_time": "2018-07-11T16:30:00Z",
    "settlement_date": "2018-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": "Chicken Tooth Music",
        "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 financial

Action: POST
Endpoint: /simulate/financial

A "financial" is a transaction message class that includes ATM transactions, PIN-debit transactions, and balance inquiries. To simulate a financial transaction, including those that involve cash-back amounts, send a POST request to the /simulate/financial endpoint.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
amount decimal Yes The transaction amount. 0.00
mid string Yes Merchant Identification number 255 char max
card_token string Yes The unique identifier of the card used in the transaction. Existing card token
pin string No The PIN number for the associated card, if required. 4 char max
is_pre_auth boolean No Set to true to mark the amount as an authorization only. true | false

Default: false
cash_back_amount decimal No The cash-back amount. 0.00
transaction_options object No Contains additional information about the transaction.
card_acceptor object No Contains attributes that describe the merchant.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The card_acceptor object

Name Type Required? Description Allowable Values
name string No Merchant name. 255 char max
address string No Merchant address. 255 char max
city string No Merchant city. 255 char max
state string No Merchant state. 2 char max
zip string No Merchant zip. 10 char max

The transaction_options object

Name Type Required? Description Allowable Values
additional_data string No Attribute of the transaction_options object. Contains additional information about the transaction.

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

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

Sample response body

{
    "type": "pindebit",
    "state": "COMPLETION",
    "token": "1038",
    "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": "2018-07-11T16:37:50Z",
        "last_modified_time": "2018-07-11T16:37:50Z",
        "transaction_token": "1039",
        "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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 166,
    "created_time": "2018-07-11T16:37:50Z",
    "user_transaction_time": "2018-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. St.",
        "city": "St. Petersburg",
        "state": "CA",
        "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

To simulate a financial advice, send a POST request to the /simulate/financial/advice endpoint and include the original_transaction_token and other authorization details in JSON format in the body of the request.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
amount decimal Yes The transaction amount. 0.00
original_transaction_token string Yes The unique identifier of the original transaction. Existing transaction token
transaction_options object No Contains additional information about the transaction.
network_fees array of objects No Simulates various types of fees levied on the transaction.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The transaction_options object

Name Type Required? Description Allowable Values
additional_data string No Attribute of the transaction_options object. Contains additional information about the transaction.

The network_fees object

Name Type Required? Description Allowable Values
type string No 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 Marqeta. Does not impact account balance.
CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.
ISSUER_FEE |
SWITCH_FEE |
PINDEBIT_ASSOC_FEE |
ACQUIRER_FEE |
INTERCHANGE_FEE |
CUR_CONV_CARDHOLDER_FEE
amount decimal No Specifies the amount of the fee. 0.00 format
credit_\debit string No Specifies whether the fee credits or debits the account balance. 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

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

{
"amount": "1.00",
"original_transaction_token": "1038"
}

Sample response body

{
    "type": "pindebit.authorization.clearing",
    "state": "COMPLETION",
    "token": "1040",
    "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": "1038",
    "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": "ed059525-d7ee-4156-a5ff-d57e65d1eae9",
        "amount": 1,
        "created_time": "2018-07-11T16:37:50Z",
        "last_modified_time": "2018-07-11T16:39:38Z",
        "transaction_token": "1041",
        "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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 167,
    "created_time": "2018-07-11T16:39:38Z",
    "user_transaction_time": "2018-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. St.",
        "city": "St. Petersburg",
        "state": "CA",
        "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

To simulate a balance inquiry, send a POST request to the /simulate/financial/balanceinquiry endpoint.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
mid string Yes Merchant Identification number 255 char max
card_token string Yes The unique identifier of the card used in the transaction. Existing card token
pin string No The PIN number for the associated card, if required. 4 char max
account_type string Yes The type of account - checking, savings, credit card. checking | savings | credit
card_acceptor object No Contains attributes that describe the merchant.
network_fees array of objects No Simulates various types of fees levied on the transaction.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The card_acceptor object

Name Type Required? Description Allowable Values
name string No Merchant name. 255 char max
address string No Merchant address. 255 char max
city string No Merchant city. 255 char max
state string No Merchant state. 2 char max
zip string No Merchant zip. 10 char max

The network_fees object

Name Type Required? Description Allowable Values
type string No 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 Marqeta. Does not impact account balance.
CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.
ISSUER_FEE |
SWITCH_FEE |
PINDEBIT_ASSOC_FEE |
ACQUIRER_FEE |
INTERCHANGE_FEE |
CUR_CONV_CARDHOLDER_FEE
amount decimal No Specifies the amount of the fee. 0.00 format
credit_\debit string No Specifies whether the fee credits or debits the account balance. 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

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

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

Sample response body

{
    "type": "pindebit.balanceinquiry",
    "state": "CLEARED",
    "token": "1042",
    "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": "2018-07-11T16:41:56Z",
    "user_transaction_time": "2018-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. St.",
        "city": "St. Petersburg",
        "state": "CA",
        "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

To simulate an ATM withdrawal, send a POST request to the /simulate/financial/withdrawal endpoint.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
mid string Yes Merchant Identification number 255 char max
card_token string Yes The unique identifier of the card used in the transaction. Existing card token
pin string No The PIN number for the associated card, if required. 4 char max
account_type string Yes The type of account - checking, savings, credit card. checking | savings | credit
amount decimal Yes The amount of money to withdraw. 0.00
card_acceptor object No Contains attributes that describe the merchant.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The card_acceptor object

Name Type Required? Description Allowable Values
name string No Merchant name. 255 char max
address string No Merchant address. 255 char max
city string No Merchant city. 255 char max
state string No Merchant state. 2 char max
zip string No Merchant zip. 10 char max

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

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

Sample response body

{
    "type": "pindebit.atm.withdrawal",
    "state": "COMPLETION",
    "token": "1045",
    "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": "2018-07-11T19:45:22Z",
        "last_modified_time": "2018-07-11T19:45:22Z",
        "transaction_token": "1046",
        "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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 129,
    "created_time": "2018-07-11T19:45:22Z",
    "user_transaction_time": "2018-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. St.",
        "city": "St. Petersburg",
        "state": "CA",
        "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. To simulate a transaction reversal, send a POST request to the /simulate/reversal endpoint and include the original_transaction_token and amount in JSON format in the body of the request.

The following tables describe the request body fields. For descriptions of the response body fields, refer to the Transactions page (the response is based on the transaction model).

Body field details

Name Type Required? Description Allowable Values
original_transaction_token string Yes The unique identifier of the transaction to reverse. Existing transaction token
amount decimal Yes The amount of the transaction. 0.00
network_fees array of objects No Simulates various types of fees levied on the transaction.
webhook object No Allows information to be posted asynchronously to endpoints hosted in your environment.

The network_fees object

Name Type Required? Description Allowable Values
type string No 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 Marqeta. Does not impact account balance.
CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.
ISSUER_FEE |
SWITCH_FEE |
PINDEBIT_ASSOC_FEE |
ACQUIRER_FEE |
INTERCHANGE_FEE |
CUR_CONV_CARDHOLDER_FEE
amount decimal No Specifies the amount of the fee. 0.00 format
credit_\debit string No Specifies whether the fee credits or debits the account balance. 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

The webhook object

Name Type Required? Description Allowable Values
endpoint string No Endpoint to which a copy of the response is sent. HTTPS URL.

250 char max.

Empty string not allowed.
username string No Username required to access the endpoint. 50 char max
password string No Password required to access the endpoint. No restrictions

Sample request body

{
"amount": "10.00",
"original_transaction_token": "1049"
}

Sample response body

{
    "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": "1047",
    "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": "2018-07-11T19:48:08Z",
        "last_modified_time": "2018-07-11T19:48:33Z",
        "transaction_token": "1050",
        "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": "2018-07-10T00:09:35Z",
                "last_modified_time": "2018-07-10T00:09:35Z"
            }
        },
        "funding_source_token": "**********b4c2",
        "user_token": "b2d2c739-a9fe-4af0-9f34-964aae4c3e31",
        "currency_code": "USD"
    },
    "duration": 113,
    "created_time": "2018-07-11T19:48:33Z",
    "user_transaction_time": "2018-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": "Chicken Tooth Music",
        "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 direct deposit

Action: POST
Endpoint: /simulate/directdeposits

To simulate a direct deposit transaction, send a POST request to the /simulate/directdeposits endpoint and include the direct deposit details in JSON format in the body of the request. You will need the deposit account number of the user to perform this operation. You can find the account number in the deposit_account.account_number field of the response when you create a new user. Alternatively, you can retrieve it by sending a GET request to the /directdeposits/accounts/{user_token} endpoint (see Direct Deposits).

Body field details

Name Type Required? Description Allowable Values
batch_header_record string Yes Fixed-length, standard, NACHA header record "5200STATE OF N.J.   INCOME TAX REFUND   2216000928PPDTAX REFUND      1504281181111000020001733"

Note: Ensure that you copy the spaces exactly.
entry_details_records array of strings Yes Array of fixed-length, standard, NACHA detail records "622026014928xxxxxxxxxxxxxx   0000012800I010660458000 SIMS   CHARLIE          140111000023391109"

Replace "xxxxxxxxxxxxxx" with the user's deposit account number.

Note: Ensure that you copy the spaces exactly.

Sample request

{
"batch_header_record":
"5200STATE OF N.J. INCOME TAX REFUND 2216000928PPDTAX REFUND 1504281181111000020001733",
"entry_details_records": [
"62202601492812346159229767 0000012800I010660458000 SIMS CHARLIE 140111000023391109",
"62202601492812346159229767 0000012800I010660458000 SIMS CHARLIE 140111000023391109"
]
}

Sample response

{
"successes": [
{
"token": "c57cb0e7-172a-4d68-a43c-a5654c923e4d",
"state": "PENDING",
"state_reason": "Success",
"account_auto_matched": true,
"user_token": "betsybird_token",
"record_created": "2016-01-26T20:20:20Z",
"record_last_modified": "2016-01-26T20:20:20Z",
"detail": {
"header": {
"record_type_code": "5",
"service_class_code": "200",
"company_name": "STATE OF N.J. ",
"company_discretionary_data": "INCOME TAX REFUND ",
"company_identification": "2216000928",
"standard_entry_class_code": "PPD",
"company_entry_description": "TAX REFUND",
"company_descriptive_date": "2016-01-26T20:20:20Z",
"effective_entry_date": "2015-04-28T00:00:00Z",
"settlement_date": "2016-04-27T20:20:20Z",
"originator_status_code": "1",
"originating_dfi_identification": "11100002",
"batch_number": "0001733"
},
"record_detail": {
"amount": 128,
"record_type_code": "6",
"transaction_code": "22",
"receiving_dfi_identification": "02601492",
"check_digit": "8",
"dfi_account_number": "___________",
"individual_identification_number": "I010660458000 ",
"individual_name": "SIMS CHARLIE ",
"discretionary_data": "14",
"addenda_record_indicator": "0",
"trace_number": "111000023391109"
}
}
},
{
"token": "d4258eff-f6ec-431e-ae19-0ea5b7e22067",
"state": "PENDING",
"state_reason": "Success",
"account_auto_matched": true,
"user_token": "betsybird_token",
"record_created": "2016-01-26T20:20:20Z",
"record_last_modified": "2016-01-26T20:20:20Z",
"detail": {
"header": {
"record_type_code": "5",
"service_class_code": "200",
"company_name": "STATE OF N.J. ",
"company_discretionary_data": "INCOME TAX REFUND ",
"company_identification": "2216000928",
"standard_entry_class_code": "PPD",
"company_entry_description": "TAX REFUND",
"company_descriptive_date": "2016-01-26T20:20:20Z",
"effective_entry_date": "2015-04-28T00:00:00Z",
"settlement_date": "2016-04-27T20:20:20Z",
"originator_status_code": "1",
"originating_dfi_identification": "11100002",
"batch_number": "0001733"
},
"record_detail": {
"amount": 128,
"record_type_code": "6",
"transaction_code": "22",
"receiving_dfi_identification": "02601492",
"check_digit": "8",
"dfi_account_number": "___________",
"individual_identification_number": "I010660458000 ",
"individual_name": "SIMS CHARLIE ",
"discretionary_data": "14",
"addenda_record_indicator": "0",
"trace_number": "111000023391109"
}
}
}
]
}