Simulations 2.0 (Beta) — Direct Deposits
Note
This feature is currently in beta and subject to change. To learn more about the beta program for this feature, contact your Marqeta representative. For older versions of Simulations, see Simulating Transactions.The Marqeta platform provides you with a production environment and a sandbox. The main difference between the production and sandbox environments is that your production environment communicates with a payment card network. This communication allows your program’s cards to pay for goods and services by initiating live transactions over the card network.
There are two types of sandbox environments available:
-
Public sandbox: A single-user environment where you can begin building your program and experiment with the Marqeta platform.
-
Private sandbox: A multi-user environment where you can integrate your application with the Marqeta platform.
All funds and transactions are simulated in both types of sandbox environments.
Unlike the production environment, a sandbox does not communicate with a card network, so the cards you create within them cannot be used to conduct real-world transactions. Therefore, you must rely on simulated transactions in order to test all objects you create within a sandbox. The sandbox environments provide a set of endpoints that let you simulate various types of card network transactions, such as authorizations, reversals, and balance inquiries. These endpoints are available only within the sandbox, so the details on this page do not apply to production.
To use the Simulations API for direct deposits:
-
Create a card in your sandbox environment.
-
Use the
/simulations/directdeposits/*endpoints to simulate transaction event types. Each endpoint is its own event type. -
Use the
/webhooksendpoint to send optional customer notifications for system events.
To use the Simulations API for card transactions, see Simulations 2.0 (Beta) — Card Transactions.
Note
You can use Postman to run requests for card transaction and direct deposit simulations endpoints. This collection of requests has been saved as a YAML file for your convenience. To access the YAML file, see Postman Collection for Simulations 2.0 (Beta).All direct deposit simulations endpoints share the same request/response model, as described below.
Request body
Copy section link
| Fields | Description |
|---|---|
account_number
string
|
The account number of the user to debit or credit. Allowable Values: An account number belonging to an active user with an active card. |
amount
decimal
|
Amount of the transaction. Allowable Values: Format: 0.00 Must be greater than zero |
company_discretionary_data
string
|
Company-specific data provided by the direct deposit originator. Allowable Values: 20 char max |
company_entry_description
string
|
Company-specific data provided by the direct deposit originator. Allowable Values: 10 char max |
company_identification
string
|
Alphanumeric code that identifies the direct deposit originator. Allowable Values: 10 char max |
company_name
string
|
Name of the direct deposit originator. Allowable Values: 16 char max |
earlyPayEligible
boolean
|
Indicates whether the transaction is eligible for early pay. Allowable Values:
|
individual_identification_number
string
|
Accounting number by which the recipient is known to the direct deposit originator. Allowable Values: 22 char max |
individual_name
string
|
Identity of the direct deposit recipient. Allowable Values: 35 char max |
settlement_date
datetime
|
Date when the credit or debit is applied. Allowable Values: Format: yyyy-mm-ddThh:mm:ssZ |
standard_entry_class_code
string
|
Three-letter code identifying the type of entry. Allowable Values: 3 char max |
token
string
|
Unique identifier of this direct deposit transition. If you do not include a token, the system generates one automatically. This token is used in other API calls, so rather than let the system generate a string, enter a string that you can remember. This value cannot be updated. Allowable Values: 36 char max |
type
string
|
Whether funds are being debited from or credited to the account. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
type
string
|
Whether funds are being debited from or credited to the account. Allowable Values:
|
state
string
|
Current status of the direct deposit record. Allowable Values:
|
state_reason
string
|
Explanation of why the direct deposit record is in the current state. Allowable Values: 255 char max |
state_reason_code
string
|
A standard code describing the reason for the current state. Allowable Values: Three-character code |
token
string
|
Unique identifier of the direct deposit record. Allowable Values: Existing direct deposit record token. |
user_token
string
|
Unique identifier of the user associated with the direct deposit record. Allowable Values: Existing user token |
amount
decimal
|
Amount being debited or credited. Allowable Values: Existing amount in 0.00 decimal format. |
business_token
string
|
Unique identifier of the business associated with the direct deposit record. Allowable Values: Existing business token |
company_discretionary_data
string
|
Company-specific data provided by the direct deposit originator. Allowable Values: 20 char max |
company_entry_description
string
|
Description of the purpose of the direct deposit. Allowable Values: 10 char max |
company_identification
string
|
Alphanumeric code that identifies the direct deposit originator. Allowable Values: 10 char max |
company_name
string
|
Name of the direct deposit originator. Allowable Values: 16 char max |
created_time
datetime
|
Date and time when the deposit account was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
direct_deposit_account_token
string
|
Unique identifier of the affected deposit account. Allowable Values: 36 char max |
individual_identification_number
string
|
Accounting number by which the recipient is known to the direct deposit originator. Allowable Values: 255 char max |
individual_name
string
|
Name of the direct deposit recipient. Allowable Values: 22 char max |
last_modified_time
datetime
|
Date and time when the direct deposit account was last modified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
settlement_date
datetime
|
Date and time when the credit or debit is applied. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
standard_entry_class_code
string
|
Three-letter code identifying the type of entry. Allowable Values:
|
Simulate credit
Copy section link
Action: POST
Endpoint: /simulations/directdeposits/credit
Use this endpoint to simulate crediting funds to a deposit account.
Simulate a direct deposit of funds to a user account by including the deposit account number of the account to be credited.
You can find the account number in the account_number field of the response when you create a new deposit account.
Alternatively, you can retrieve it by sending a GET request to the /depositaccounts/user/{user_token} endpoint.
For more information, see Direct Deposit.
See the full request body structure at Request body.
Sample request body
Copy section link
See the full response body structure at Response body.
Simulate debit
Copy section link
Action: POST
Endpoint: /simulations/directdeposits/debit
Use this endpoint to simulate debiting funds from a deposit account.
Simulate a direct deposit of funds to a user account by including the deposit account number of the account to be debited.
You can find the account number in the account_number field of the response when you create a new deposit account.
Alternatively, you can retrieve it by sending a GET request to the /depositaccounts/user/{user_token} endpoint.
For more information, see Direct Deposit.
See the full request body structure at Request body.
Sample request body
Copy section link
See the full response body structure at Response body.