Simulating Transactions

The Marqeta platform provides you with both a production environment and a test environment (the latter known as the shared sandbox). The most significant functional difference between these two environments is that your production environment communicates with a payment card network. This communication allows your cards to pay for goods and services by initiating transactions over the card network.

The shared sandbox, on the other hand, does not communicate with a card network and the cards you create within it 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 shared sandbox.

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

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

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. 50 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
cash_back_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 holder's seven-digit zip code. To pass AVS, must match the zip code on record.

The card_acceptor object

Name Type Required? Description Allowable Values
mcc string No Merchant category code. 5 char max
partial_approval_capable boolean No Whether the response can approve an amount less than or equal to the requested amount. true | false

Default: false
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 or postal code. 10 char max
country string No Merchant country. 40 char max
ecommerce_security_level_indicator string No Contains the fields representing the security protocol and cardholder authentication type associated with the transaction. 0-9

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": "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": "2018-07-11T16:30:00Z",
        "last_modified_time": "2018-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": "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 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

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": "9cbbdb91-81bb-4d26-acea-2734a67a96d2"
}

Sample response body

{
    "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": "2018-07-11T16:30:00Z",
        "last_modified_time": "2018-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": "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

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

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. 50 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
mcc string No Merchant category code. 5 char max
partial_approval_capable boolean No Whether the response can approve an amount less than or equal to the requested amount. true | false

Default: false
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 or postal code. 10 char max
country string No Merchant country. 40 char max
ecommerce_security_level_indicator string No Contains the fields representing the security protocol and cardholder authentication type associated with the transaction. 0-9

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

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

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

Send the following request to simulate a refund type transaction.

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

Sample response body

The following response shows an authorization.clearing type transaction.

{
    "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": "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
    }
}

The following response shows a refund type transaction.

{
"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": "2019-02-12T22:32:25Z",
"user_transaction_time": "2019-02-12T22:32:25Z",
"settlement_date": "2019-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": "2019-02-12T22:32:25Z",
"last_modified_time": "2019-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": "2019-01-28T19:20:33Z",
"last_modified_time": "2019-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. St.",
"city": "St. Petersburg",
"state": "CA",
"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

Name Type Required? Description Allowable Values
amount decimal Yes The transaction amount. 0.00
mid string Yes Merchant Identification number 50 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
mcc string No Merchant category code. 5 char max
partial_approval_capable boolean No Whether the response can approve an amount less than or equal to the requested amount. true | false

Default: false
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 or postal code. 10 char max
country string No Merchant country. 40 char max
ecommerce_security_level_indicator string No Contains the fields representing the security protocol and cardholder authentication type associated with the transaction. 0-9

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": "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": "2018-07-11T16:37:50Z",
        "last_modified_time": "2018-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": "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

Simulate an authorization.clearing type transaction by including the original_transaction_token of an authorization type transaction. To simulate a pindebit.authorization.clearing type transaction, include the original_transaction_token of a pindebit type transaction.

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": "0ae44166-058d-4882-b39f-13fea8c6e387"
}

Sample response body

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

{
    "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": "2018-07-11T16:37:50Z",
        "last_modified_time": "2018-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": "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

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

Body field details

Name Type Required? Description Allowable Values
mid string Yes Merchant Identification number 50 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
mcc string No Merchant category code. 5 char max
partial_approval_capable boolean No Whether the response can approve an amount less than or equal to the requested amount. true | false

Default: false
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 or postal code. 10 char max
country string No Merchant country. 40 char max
ecommerce_security_level_indicator string No Contains the fields representing the security protocol and cardholder authentication type associated with the transaction. 0-9

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

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

Body field details

Name Type Required? Description Allowable Values
mid string Yes Merchant Identification number. 50 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
mcc string No Merchant category code. 5 char max
partial_approval_capable boolean No Whether the response can approve an amount less than or equal to the requested amount. true | false

Default: false
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 or postal code. 10 char max
country string No Merchant country. 40 char max
ecommerce_security_level_indicator string No Contains the fields representing the security protocol and cardholder authentication type associated with the transaction. 0-9

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": "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": "2018-07-11T19:45:22Z",
        "last_modified_time": "2018-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": "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.

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

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": "94c97e14-7915-4806-a609-dbb02c35c413"
}

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": "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": "2018-07-11T19:48:08Z",
        "last_modified_time": "2018-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": "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

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 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. For more information, see Direct Deposits.

If type is CREDIT, the response contains a simulated transaction message of the type directdeposits.credit. If type is DEBIT, the response contains a simulated transaction message of the type directdeposits.debit.

Body field details

Name Type Required? Description Allowable Values
amount string Yes The amount of the direct deposit.
type string Yes Indicates whether the direct deposit is a debit or credit. CREDIT | DEBIT
account_number string Yes The account number of the user to debit or credit. An account number belonging to an active user.

Send a GET request to the /directdeposits/accounts/{user_token} endpoint to retrieve the account number of a user.
settlement_date string Yes The date on which the credit or debit will be applied if immediate credit is not enabled. yyyy-MM-dd

Sample requests

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

{
"amount": 10,
"type": "CREDIT",
"account_number": "00002129265673728",
"settlement_date": "2018-07-11T19:56:53.440Z"
}

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

{
"amount": 10,
"type": "DEBIT",
"account_number": "00002129265673728",
"settlement_date": "2019-02-07T22:01:25Z"
}

Sample responses

The following response shows a directdeposit.credit type transaction.

{
"token": "ce2002fd-5e9a-4c9b-a82d-cc74da4e8280",
"amount": 10,
"type": "CREDIT",
"state": "PENDING",
"settlement_date": "2018-07-11T19:56:53Z",
"state_reason": "Newly created",
"user_token": "d5e46927-0c84-4010-af80-5844fce8c154",
"created_time": "2018-07-12T22:49:24Z",
"last_modified_time": "2018-07-12T22:49:24Z"
}

The following response shows a directdeposit.debit type transaction.

{
"token": "60ebce39-4d66-4d60-a4cb-46446c0aca28",
"amount": 1,
"type": "DEBIT",
"state": "PENDING",
"settlement_date": "2019-02-07T22:01:25Z",
"state_reason": "Newly created",
"created_time": "2019-02-07T22:39:49Z",
"last_modified_time": "2019-02-07T22:39:49Z"
}


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

Name Type Required? Description Allowable Values
amount decimal Yes Amount of the transaction. 0.00
Must be greater than zero
card_token string Yes Unique identifier of the card receiving original credit. Existing card token
36 char max
mid string Yes Merchant Identifier of the merchant participating in the transaction. 50 char max
card_acceptor object No Contains attributes that describe the merchant.
screening_score string No 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.
000-100 or 999
Value of 999 means no score available
type string Yes Type of original credit transaction. 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 No Contains sender-related information.
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
mcc string No Merchant category code. 5 char max
partial_approval_capable boolean No Whether the response can approve an amount less than the requested amount. true | false

Default: false
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 or postal code. 10 char max
country string No Merchant country. 40 char max
ecommerce_security_level_indicator string No Represents the security protocol and cardholder authentication type associated with the transaction. 0-9

The sender_data object

Name Type Required? Description Allowable Values
sender_name string No Sender full name. 255 char max
sender_reference_number string No Transaction reference number provided by the originating bank used to uniquely identify the sender 16 char max
sender_account_number string No Sender's simulated account number. 34 char max
sender_address string No Sender street address. 255 char max
sender_city string No Sender city. 36 char max
sender_state string No Sender state. 2 char max
sender_country string No Sender country. 40 char max
funding_source string No Sender's simulated account from which the OCT draws funds. credit |
debit |
prepaid |
deposit_account |
cash |
mobile_money_account |
non_visa_credit

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

Send the following request to simulate a disbursement type transaction.

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

Sample response body

The following response shows a disbursement type transaction.

{
    "transaction": {
        "type": "original.credit.auth_plus_capture",
        "state": "COMPLETION",
        "identifier": "48266",
        "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": "2019-07-08T23:47:04Z",
        "user_transaction_time": "2019-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": "2019-02-14T00:57:02Z",
            "last_modified_time": "2019-02-14T00:57:02Z"
        },
        "store": {
            "name": "Chicken Tooth Music",
            "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": "2019-02-14T01:18:38Z",
            "last_modified_time": "2019-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": "2019-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        07012019",
        "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.           "
    }
}