/
15 minute read
November 30, 2022

Deposit Accounts (Beta)

The Marqeta platform’s deposit account feature enables you to manage the creation, maintenance, and lifecycle of a deposit account.

You can also look up a user by their associated plain text deposit account number or list all the deposit accounts associated with a specified user.

Note
Using the deposit account feature requires additional configuration. If you are interested in using this feature, contact your Marqeta representative for more information.

Create deposit account

Action: POST
Endpoint: /depositaccounts

Creates a new deposit account for a user or business.

Before you can create a new deposit account, the associated user must successfully pass KYC. (You can also set the manual_override field of POST /kyc to true in the event that you performed the verification through another mechanism, such as with an alternative KYC provider or directly with the account holder). For more information, see About KYC Verification.

An active, issued card—at either the parent or the child level—is required before creating an account with the type field set to DEPOSIT_ACCOUNT. In contrast, you can create an account without an issued card when the type field is set to CHECKING; however, you must issue and activate a card before the checking account can be used to transact.

Note
Each cardholder is limited to five deposit accounts, including any accounts in the ACTIVE or SUSPENDED state. Contact your Marqeta representative if you need to raise this value.

Request body

Fields Description

token

string
Optional

Unique identifier of the deposit account.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

user_token OR business_token

string
Required

User or business for which to create the deposit account. Pass either a user_token or business_token. Performs a non-case-sensitive match.

Allowable Values:

Existing user or business token.

NOTE: If you pass a business token here, you can only create a DEPOSIT_ACCOUNT, and not a CHECKING account. See the type field below for details.

type

string
Optional

Type of deposit account being created.

Allowable Values:

  • DEPOSIT_ACCOUNT: An ACH account that supports automatic direct deposit transactions. Reserved for prepaid card programs.

  • CHECKING: A consumer Demand Deposit Account (DDA) offering features typically associated with checking accounts.

Default value:
DEPOSIT_ACCOUNT

NOTE: This field is not returned in the response.

customer_due_diligence

array of objects
Conditionally required

Array containing Customer Due Diligence (CDD) data associated with the account holder specified by user_token. Required when the type field is set to CHECKING. For details, see About Customer Due Diligence.

Allowable Values:

Array of objects with valid CDD question/answer pairs, as described in CDD Data Object.

Response body

Fields Description

account_number

string
Returned

Account number assigned to the deposit account.

Allowable Values:

13-17 char max, depending on the program.

routing_number

string
Returned

Routing number assigned to the deposit account.

Allowable Values:

9 char max

token

string
Returned

Unique identifier of the deposit account.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

User or business to whom the deposit account belongs.

Allowable Values:

36 char max

state

string
Returned

Status of the deposit account.

Allowable Values:

ACTIVE

type

string
Returned

Type of deposit account created.

Allowable Values:

DEPOSIT_ACCOUNT, CHECKING

created_time

string
Returned

Date and time when the deposit account was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

last_modified_time

string
Returned

Date and time when the deposit account was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve deposit account

Action: GET
Endpoint: /depositaccounts/{token}

Retrieves a specified deposit account. Include the token path parameter to indicate the deposit account to retrieve.

URL path parameters

Fields Description

token

string
Required

Token of the deposit account.

Allowable Values:

Existing deposit account token.

Response body

Fields Description

account_number

string
Returned

Account number assigned to the deposit account.

Allowable Values:

13-17 char max, depending on the program.

routing_number

string
Returned

Routing number assigned to the deposit account.

Allowable Values:

9 char max

token

string
Returned

Unique identifier of the deposit account.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

User or business associated with the deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

type

string
Returned

Type of deposit account.

Allowable Values:

  • DEPOSIT_ACCOUNT: An ACH account that supports automatic direct deposit transactions. Reserved for prepaid card programs.

  • CHECKING: A consumer Demand Deposit Account (DDA) offering features typically associated with checking accounts.

created_time

string
Returned

Date and time when the deposit account was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

last_modified_time

string
Returned

Date and time when the deposit account was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List deposit accounts

Action: GET
Endpoint: /depositaccounts/user/{token}

Retrieves a list of all the deposit accounts associated with the specified account holder.

This endpoint supports pagination and field filtering.

URL path parameters

Fields Description

token

string
Required

Token identifying the user or business whose deposit accounts you want to retrieve.

Allowable Values:

36 char max

Response body

Fields Description

account_number

string
Returned

Account number assigned to the deposit account.

Allowable Values:

13-17 char max, depending on the program.

routing_number

string
Returned

Routing number assigned to the deposit account.

Allowable Values:

9 char max

token

string
Returned

Unique identifier of the deposit account.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

Unique identifier of the user or business associated with the deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

type

string
Returned

Type of deposit account.

Allowable Values:

DEPOSIT_ACCOUNT, CHECKING

created_time

string
Returned

Date and time when the deposit account was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

last_modified_time

string
Returned

Date and time when the deposit account was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Look up user by deposit account

Action: GET
Endpoint: /depositaccounts/account/{account_number}/user

Looks up a user by their associated plain text deposit account number.

URL path parameters

Fields Description

account_number

string
Required

Deposit account number of the user you are looking up.

Allowable Values:

Existing 13-17 digit deposit account number.

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Create deposit account transition

Action: POST
Endpoint: /depositaccounts/transitions

Creates a transition record to activate, suspend, or deactivate a deposit account.

Warning
Accounts in the TERMINATED state cannot be transitioned to another state. TERMINATED is a final state.

Request body

Fields Description

token

string
Optional

Unique identifier of the account transitions record.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

account_token

string
Required

Unique identifier of the deposit account.

Allowable Values:

36 char max

state

string
Required

Status of the account transitions record.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

channel

string
Required

Channel associated with the account transitions record.

Most account transitions use the API channel, and the SYSTEM channel is typically reserved for use by the Marqeta platform. For a detailed description of each of these values, see The channel field (response).

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM

reason

string
Optional

Explanation of why the account transitions record was created.

Allowable Values:

255 char max

Response body

Fields Description

token

string
Returned

Unique identifier of the account transitions record.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

Unique identifier of the user or business associated with the account transitions record.

Allowable Values:

36 char max

account_token

string
Returned

Unique identifier of the deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

channel

string
Returned

Channel associated with the account transitions record.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM

reason

string
Conditionally returned

Explanation of why the account transitions record was created. This string is returned if you included it in your POST request.

Allowable Values:

255 char max

created_time

string
Returned

Date and time when the deposit transition was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve deposit account transition

Action: GET
Endpoint: /depositaccounts/transitions/{token}

Retrieves the specified deposit account transition.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the account transitions record.

Allowable Values:

36 char max

Response body

Fields Description

token

string
Returned

Unique identifier of the account transitions record.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

Unique identifier of the user or business associated with the account transitions record.

Allowable Values:

36 char max

account_token

string
Returned

Unique identifier of the deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the account transitions record.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

channel

string
Returned

Channel associated with the account transitions record.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM

reason

string
Conditionally returned

Explanation of why the account transitions record was created. This string is returned if you included it in your POST request.

Allowable Values:

255 char max

created_time

string
Returned

Date and time when the account transitions record was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve all deposit account transitions

Action: GET
Endpoint: /depositaccounts/{user_token}/transitions

Retrieves a list of all transitions of all accounts that are associated with the specified account holder.

This endpoint supports pagination and field filtering.

URL path parameters

Fields Description

user_token

string
Required

Unique identifier of the user whose account transitions you want to retrieve.

Allowable Values:

36 char max

Response body

Fields Description

token

string
Returned

Unique identifier of the account transitions record.

Allowable Values:

36 char max

user_token

string
Returned

Unique identifier of the user whose account transitions you want to retrieve.

Allowable Values:

36 char max

account_token

string
Returned

Unique identifier of the deposit account.

Allowable Values:

36 char max

state

string
Returned

Status to which the deposit account was transitioned.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

channel

string
Returned

Channel associated with the account transitions record.

Allowable Values:

API, ADMIN, IVR, FRAUD, SYSTEM

reason

string
Conditionally returned

Explanation of why the account transitions record was created. This string is returned if you included it in your POST request.

Allowable Values:

255 char max

created_time

string
Returned

Date and time when the account transitions record was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve customer due diligence information

Action: GET
Endpoint: /depositaccounts/{token}/cdd

Retrieves a list of the customer due diligence (CDD) questions and answers associated with the specified account holder and DDA.

For more information on CDD, see About Customer Due Diligence.

URL path parameters

Fields Description

token

string
Required

Token identifying the DDA whose CDD questions and answers you want to retrieve.

Allowable Values:

36 char max

Response body

Fields Description

customer_due_diligence_list

array of objects
Returned

An array containing a customer_due_diligence object for each due diligence question/answer pair related to the specified account token.

Each customer_due_diligence object contains the fields described in the customer_due_diligence data object.

Allowable Values:

An array of valid customer_due_diligence data objects.

The customer_due_diligence data object

Fields Description

question

string
Returned

Unique identifier of the CDD question whose answer is stored in the customer_due_diligence object. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value, for example dda_002_cdd_01_expmondep.

answer

string
Returned

Unique identifier of the answer supplied by the account holder in response to the CDD question specified by question.

Allowable Values:

type

string
Returned

Type of account whose CDD data is contained in this object.

Allowable Values:

CHECKING

bank

string
Returned

Name of the financial institution requesting these CDD questions and answers. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value

token

string
Returned

Unique identifier of this CDD response.

Allowable Values:

36 char max

account_token

string
Returned

Unique identifier of the associated deposit account.

Allowable Values:

36 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Update customer due diligence information

Action: PUT
Endpoint: /depositaccounts/{token}/cdd/{cddtoken}

Updates the answer to a customer due diligence (CDD) question associated with the specified account holder and DDA.

Note
Each CDD question must be updated separately; you cannot update multiple questions in a single request.

URL path parameters

Fields Description

token

string
Required

Account token identifying the DDA whose CDD question you want to update.

Allowable Values:

Existing account token.

cddtoken

string
Required

Token identifying the CDD question whose answer you want to update.

Allowable Values:

Existing CDD token.

Request body

Fields Description

answer

string
Required

The updated answer value to the CDD question specified by cddtoken.

Allowable Values:

Response body

Fields Description

question

string
Returned

Unique identifier of the CDD question whose updated answer is specified by answer. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value, for example dda_002_cdd_01_expmondep.

answer

string
Returned

Unique identifier of the updated answer supplied by the account holder in response to the CDD question specified by question.

Allowable Values:

type

string
Returned

Type of account whose CDD data is being updated.

Allowable Values:

CHECKING

bank

string
Returned

Name of the financial institution requesting these CDD questions and answers. This value is provided to you by Marqeta.

Allowable Values:

A Marqeta-assigned value

token

string
Returned

Unique identifier of this CDD response.

Allowable Values:

36 char max

account_token

string
Returned

Unique identifier of the associated deposit account.

Allowable Values:

36 char max

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter