DOCS

New!

/

25 minute read

August 2, 2019

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

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Body field details

Fields Description

card_token

string, required

The unique identifier of the card involved in the transaction.

Allowable Values:

255 char max

amount

decimal, required

The amount of the transaction.

Allowable Values:

0.00

mid

string, required

The Merchant Identifier of the merchant participating in the transaction.

Allowable Values:

50 char max

is_pre_auth

boolean, optional

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

Allowable Values:

true, false

Default value: false

card_acceptor

object, optional

Contains attributes that describe the merchant.

Allowable Values:

card_options

object, optional

Contains attributes that govern card usage.

Allowable Values:

transaction_options

object, optional

Contains additional information about the transaction.

Allowable Values:

pin

string, optional

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

Allowable Values:

4 char max

cash_back_amount

decimal, optional

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

Allowable Values:

0.00

network_fees

array of objects, optional

Simulates various types of fees levied on the transaction.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The card_options object

Fields Description

cvv

string, optional

The CVV2 number for the card.

Allowable Values:

4 char max

expiration

string, optional

The expiration date of the card.

Allowable Values:

mmdd

billing_address

object, optional

Used for AVS (address verification system). The address-related fields in this object are verified against known values.

Allowable Values:

card_present

boolean, optional

True requires that the card be present for the transaction.

Allowable Values:

true, false

Default value: false

The card_options.billing_address object

Fields Description

first_name

string, optional

Card holder’s first name.

Allowable Values:

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

last_name

string, optional

Card holder’s last name.

Allowable Values:

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

address

string, optional

Card holder’s street address.

Allowable Values:

To pass AVS, must match the address on record.

zip

string, optional

Card holder’s seven-digit postal code.

Allowable Values:

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

The card_acceptor object

Fields Description

mcc

string, optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean, optional

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

Allowable Values:

true | false

Default: false

name

string, optional

Merchant name.

Allowable Values:

255 char max

address

string, optional

Merchant address.

Allowable Values:

255 char max

city

string, optional

Merchant city.

Allowable Values:

255 char max

state

string, optional

Merchant state.

Allowable Values:

2 char max

zip

string, optional

Merchant zip or postal code.

Allowable Values:

10 char max

country

string, optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string, optional

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

Allowable Values:

0-9

The transaction_options object

Fields Description

additional_data

string, optional

Additional information about the transaction.

Allowable Values:

255 char max

The network_fees object

Fields Description

type

string, optional

Specifies the type of fee.

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

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

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

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

  • INTERCHANGE_FEE – Fee charged per transaction by Marqeta. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE

amount

decimal, optional

Specifies the amount of the fee.

Allowable Values:

0.00 format

credit_debit

string, optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

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

Fee type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate authorization advice

Action: POST
Endpoint: /simulate/authorization/advice

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

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

Body field details

Fields Description

amount

decimal, required

The amount of the transaction.

Allowable Values:

0.00

original_transaction_token

string, required

The unique token that identifies the original transaction.

Allowable Values:

Existing transaction token

transaction_options

object, optional

Contains additional information about the transaction.

Allowable Values:

network_fees

array of objects, optional

Simulates various types of fees levied on the transaction.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The transaction_options object

Fields Description

additional_data

string, optional

Additional information about the transaction.

Allowable Values:

255 char max

The network_fees object

Fields Description

type

string, optional

Specifies the type of fee.

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

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

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

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

  • INTERCHANGE_FEE – Fee charged per transaction by Marqeta. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE

amount

decimal, optional

Specifies the amount of the fee.

Allowable Values:

0.00 format

credit_debit

string, optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

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

Fee type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

No restrictions

Sample request body

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate clearing or refund

Action: POST
Endpoint: /simulate/clearing

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Body field details

Fields Description

original_transaction_token

string, required

The unique identifier of the transaction to clear.

Allowable Values:

Existing transaction token

amount

decimal, required

The amount of the transaction.

Allowable Values:

0.00

force_post

boolean, optional

Set to true to simulate a forced clearing transaction.

Note
If you set this field to true, you must also set the original_transaction_token field to an existing transaction token (the transaction does not need to be related).

Allowable Values:

true, false

Default value: false

is_refund

boolean, optional

Set to true to simulate a refund transaction.

Allowable Values:

true, false

Default value: false

mid

string, optional

Merchant Identification number.

Allowable Values:

50 char max

card_acceptor

object, optional

Contains attributes that describe the merchant.

Allowable Values:

network_fees

array of objects, optional

Simulates various types of fees levied on the transaction.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The card_acceptor object

Fields Description

mcc

string, optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean, optional

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

Allowable Values:

true | false

Default: false

name

string, optional

Merchant name.

Allowable Values:

255 char max

address

string, optional

Merchant address.

Allowable Values:

255 char max

city

string, optional

Merchant city.

Allowable Values:

255 char max

state

string, optional

Merchant state.

Allowable Values:

2 char max

zip

string, optional

Merchant zip or postal code.

Allowable Values:

10 char max

country

string, optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string, optional

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

Allowable Values:

0-9

The network_fees object

Fields Description

type

string, optional

Specifies the type of fee.

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

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

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

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

  • INTERCHANGE_FEE – Fee charged per transaction by Marqeta. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE

amount

decimal, optional

Specifies the amount of the fee.

Allowable Values:

0.00 format

credit_debit

string, optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

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

Fee type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

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

Is this helpful?

Send the following request to simulate a refund type transaction.

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

Is this helpful?

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
     }
 }

Is this helpful?

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
    }
}

Is this helpful?

Simulate financial

Action: POST
Endpoint: /simulate/financial

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

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

Body field details

Fields Description

amount

decimal, required

The transaction amount.

Allowable Values:

0.00

mid

string, required

Merchant Identification number

Allowable Values:

50 char max

card_token

string, required

The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token

pin

string, optional

The PIN number for the associated card, if required.

Allowable Values:

4 char max

is_pre_auth

boolean, optional

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

Allowable Values:

true, false

Default value: false

cash_back_amount

decimal, optional

The cash-back amount.

Allowable Values:

0.00

transaction_options

object, optional

Contains additional information about the transaction.

Allowable Values:

card_acceptor

object, optional

Contains attributes that describe the merchant.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The card_acceptor object

Fields Description

mcc

string, optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean, optional

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

Allowable Values:

true | false

Default: false

name

string, optional

Merchant name.

Allowable Values:

255 char max

address

string, optional

Merchant address.

Allowable Values:

255 char max

city

string, optional

Merchant city.

Allowable Values:

255 char max

state

string, optional

Merchant state.

Allowable Values:

2 char max

zip

string, optional

Merchant zip or postal code.

Allowable Values:

10 char max

country

string, optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string, optional

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

Allowable Values:

0-9

The transaction_options object

Fields Description

additional_data

string, optional

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

Allowable Values:

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

No restrictions

Sample request body

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate financial advice

Action: POST
Endpoint: /simulate/financial/advice

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Fields Description

amount

decimal, required

The transaction amount.

Allowable Values:

0.00

original_transaction_token

string, required

The unique identifier of the original transaction.

Allowable Values:

Existing transaction token

transaction_options

object, optional

Contains additional information about the transaction.

Allowable Values:

network_fees

array of objects, optional

Simulates various types of fees levied on the transaction.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The transaction_options object

Fields Description

additional_data

string, optional

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

Allowable Values:

The network_fees object

Fields Description

type

string, optional

Specifies the type of fee.

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

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

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

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

  • INTERCHANGE_FEE – Fee charged per transaction by Marqeta. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE

amount

decimal, optional

Specifies the amount of the fee.

Allowable Values:

0.00 format

credit_debit

string, optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

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

Fee type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

No restrictions

Sample request body

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate balance inquiry

Action: POST
Endpoint: /simulate/financial/balanceinquiry

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Body field details

Fields Description

mid

string, required

Merchant Identification number

Allowable Values:

50 char max

card_token

string, required

The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token

pin

string, optional

The PIN number for the associated card, if required.

Allowable Values:

4 char max

account_type

string, required

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

Allowable Values:

checking, savings, credit

card_acceptor

object, optional

Contains attributes that describe the merchant.

Allowable Values:

network_fees

array of objects, optional

Simulates various types of fees levied on the transaction.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The card_acceptor object

Fields Description

mcc

string, optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean, optional

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

Allowable Values:

true | false

Default: false

name

string, optional

Merchant name.

Allowable Values:

255 char max

address

string, optional

Merchant address.

Allowable Values:

255 char max

city

string, optional

Merchant city.

Allowable Values:

255 char max

state

string, optional

Merchant state.

Allowable Values:

2 char max

zip

string, optional

Merchant zip or postal code.

Allowable Values:

10 char max

country

string, optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string, optional

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

Allowable Values:

0-9

The network_fees object

Fields Description

type

string, optional

Specifies the type of fee.

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

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

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

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

  • INTERCHANGE_FEE – Fee charged per transaction by Marqeta. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE

amount

decimal, optional

Specifies the amount of the fee.

Allowable Values:

0.00 format

credit_debit

string, optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

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

Fee type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

No restrictions

Sample request body

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate ATM withdrawal

Action: POST
Endpoint: /simulate/financial/withdrawal

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Body field details

Fields Description

mid

string, required

Merchant Identification number.

Allowable Values:

50 char max

card_token

string, required

The unique identifier of the card used in the transaction.

Allowable Values:

Existing card token

pin

string, optional

The PIN number for the associated card, if required.

Allowable Values:

4 char max

account_type

string, required

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

Allowable Values:

checking, savings, credit

amount

decimal, required

The amount of money to withdraw.

Allowable Values:

0.00

card_acceptor

object, optional

Contains attributes that describe the merchant.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The card_acceptor object

Fields Description

mcc

string, optional

Merchant category code.

Allowable Values:

5 char max

partial_approval_capable

boolean, optional

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

Allowable Values:

true | false

Default: false

name

string, optional

Merchant name.

Allowable Values:

255 char max

address

string, optional

Merchant address.

Allowable Values:

255 char max

city

string, optional

Merchant city.

Allowable Values:

255 char max

state

string, optional

Merchant state.

Allowable Values:

2 char max

zip

string, optional

Merchant zip or postal code.

Allowable Values:

10 char max

country

string, optional

Merchant country.

Allowable Values:

40 char max

ecommerce_security_level_indicator

string, optional

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

Allowable Values:

0-9

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

No restrictions

Sample request body

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate reversal

Action: POST
Endpoint: /simulate/reversal

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

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

Body field details

Fields Description

original_transaction_token

string, required

The unique identifier of the transaction to reverse.

Allowable Values:

Existing transaction token

amount

decimal, required

The amount of the transaction.

Allowable Values:

0.00

network_fees

array of objects, optional

Simulates various types of fees levied on the transaction.

Allowable Values:

webhook

object, optional

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

Allowable Values:

The network_fees object

Fields Description

type

string, optional

Specifies the type of fee.

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

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

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

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

  • INTERCHANGE_FEE – Fee charged per transaction by Marqeta. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the card holder by Marqeta. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE

amount

decimal, optional

Specifies the amount of the fee.

Allowable Values:

0.00 format

credit_debit

string, optional

Specifies whether the fee credits or debits the account balance.

Allowable Values:

C, D

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

Fee type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values:

HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values:

50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values:

No restrictions

Sample request body

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

Is this helpful?

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
     }
 }

Is this helpful?

Simulate direct deposit

Action: POST
Endpoint: /simulate/directdeposits

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Fields Description

amount

string, required

The amount of the direct deposit.

Allowable Values:

type

string, required

Indicates whether the direct deposit is a debit or credit.

Allowable Values:

CREDIT, DEBIT

account_number

string, required

The account number of the user to debit or credit.

Allowable Values:

An account number belonging to an active user.

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

settlement_date

string, required

The date on which the credit or debit will be applied if immediate credit is not enabled.

Allowable Values:

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

Is this helpful?

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

Is this helpful?

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

Is this helpful?

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

Is this helpful?

Simulate OCT

Action: POST
Endpoint: /simulate/financial/originalcredit

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

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

Body field details

Fields Description

amount

decimal, required

Amount of the transaction.

Allowable Values: 0.00

Must be greater than zero

card_token

string, required

Unique identifier of the card receiving original credit.

Allowable Values: Existing card token

36 char max

mid

string, required

Merchant Identifier of the merchant participating in the transaction.

Allowable Values: 50 char max

card_acceptor

object, optional

Contains attributes that describe the merchant.

screening_score

string, optional

Sanctions screening score to assist with meeting Anti-Money Laundering (AML) obligations.

Higher scores indicate that the sender’s data more closely resembles an entry on the regulatory watchlist.

Allowable Values: 000-100 or 999

Value of 999 means no score available

type

string, required

Type of original credit transaction.

Allowable Values: account_to_account |

person_to_person |

wallet_transfer |

money_transfer_by_bank |

business_to_business |

disbursement |

government_disbursement |

gambling_payout |

loyalty |

merchant_disbursement |

online_gambling_payout |

pension_disbursement |

prepaid_loads |

card_bill_payment |

bill_payment |

cash_claim |

cash_in |

cash_out |

mobile_air_time_payment |

money_transfer_by_merchant |

face_to_face_merchant_payment |

government_payment |

payments_goods_services

sender_data

object, optional

Contains sender-related information.

webhook

object, optional

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

The card_acceptor object

Fields Description

mcc

string, optional

Merchant category code.

Allowable Values: 5 char max

partial_approval_capable

boolean, optional

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

Allowable Values: true, false

Default: false

name

string, optional

Merchant name.

Allowable Values: 255 char max

address

string, optional

Merchant address.

Allowable Values: 255 char max

city

string, optional

Merchant city.

Allowable Values: 255 char max

state

string, optional

Merchant state.

Allowable Values: 2 char max

zip

string, optional

Merchant zip or postal code.

Allowable Values: 10 char max

country

string, optional

Merchant country.

Allowable Values: 40 char max

ecommerce_security_level_indicator

string, optional

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

Allowable Values: 0-9

The sender_data object

Fields Description

sender_name

string, optional

Sender full name.

Allowable Values: 255 char max

sender_reference_number

string, optional

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

Allowable Values: 16 char max

sender_account_number

string, optional

Sender’s simulated account number.

Allowable Values: 34 char max

sender_address

string, optional

Sender street address.

Allowable Values: 255 char max

sender_city

string, optional

Sender city.

Allowable Values: 36 char max

sender_state

string, optional

Sender state.

Allowable Values: 2 char max

sender_country

string, optional

Sender country.

Allowable Values: 40 char max

funding_source

string, optional

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

Allowable Values: credit, debit, prepaid, deposit_account, cash, mobile_money_account, non_visa_credit

The webhook object

Fields Description

endpoint

string, optional

Endpoint to which a copy of the response is sent.

Allowable Values: HTTPS URL

250 char max

Empty string not allowed

username

string, optional

Username required to access the endpoint.

Allowable Values: 50 char max

password

string, optional

Password required to access the endpoint.

Allowable Values: No restrictions

Get started now!

Sign up today and get access to Marqeta's API Explorer

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.           "
    }
}

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.