Direct Deposits

The Marqeta platform's direct deposit feature enables third parties to credit or debit the general purpose account (GPA) of a Marqeta account holder.

When you create a new user or business, the Marqeta platform generates an account number and routing number and associates these numbers with the account holder's GPA. The account holder provides these numbers to any third party who wants to debit or credit the GPA. Each account holder is limited to one deposit account and must have an active card to enable the direct deposit feature.

You can configure an existing deposit account to enable immediate credits or debits. You also can change the state of an individual deposit.

Note: Using the Direct Deposit feature requires additional configuration. If you are interested in using this feature, contact your Marqeta Customer Success representative for more information.

Retrieve direct deposit record

Action: GET
Endpoint: /directdeposits/{token}

Retrieve a direct deposit record. Include the token path parameter to indicate the direct deposit record to retrieve.

A direct deposit record stores the details corresponding to a single direct deposit action, such as the type (debit or credit), amount, and associated dates and times.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the direct deposit record to retrieve. Existing direct deposit record token.

Use a GET request to /directdeposits to retrieve direct deposit tokens.

Sample response

{
"token": "00acce2b-cead-45ab-9417-f8a62326c0d5",
"amount": 50.00,
"type": "CREDIT",
"state": "PENDING",
"settlement_date": "2018-12-31T00:00:00Z",
"state_reason": "New credit",
"user_token": "bluebird_token",
"created_time": "2018-05-12T21:02:37Z",
"last_modified_time": "2018-05-12T21:02:37Z"
}


List direct deposit records

Action: GET
Endpoint: /directdeposits

Retrieve a list of all direct deposit records.

This endpoint supports pagination and field filtering.

Query parameters

Name Type Required? Description Allowable Values
user_token

OR

business_token
string No The account holder for which to return records. Pass either a user_token or business_token. Performs a non-case-sensitive match. Existing user or business token.

Use a GET request to retrieve tokens from /users or /businesses.
direct_deposit_state string No Performs a case-sensitive match on the direct_deposit_state field. PENDING | APPLIED | REVERSED | REJECTED

Sample response

{
"count" : 5,
"start_index" : 0,
"end_index" : 4,
"is_more" : true,
"data" : [ {
"token" : "ff035886-5a59-4e9a-86a1-dba8a7cf9c06",
"amount" : 50.00,
"type" : "CREDIT",
"state" : "PENDING",
"settlement_date" : "2018-04-05T00:00:00Z",
"state_reason" : "Newly created",
"user_token" : "3f0aa078-1db7-47cf-abf4-3a7ae7cd9e20",
"created_time" : "2018-04-05T20:37:40Z",
"last_modified_time" : "2018-04-05T20:37:40Z"
}, {
"token" : "c4ec050d-3e49-4fa4-9fea-11bc18506be3",
"amount" : 50.00,
"type" : "CREDIT",
"state" : "APPLIED",
"settlement_date" : "2018-04-05T00:00:00Z",
"state_reason" : "Success credit immediately",
"business_token" : "a86c1926-30ab-41fe-8c75-ba4a0baef1fd",
"created_time" : "2018-04-05T20:37:40Z",
"last_modified_time" : "2018-04-05T20:37:40Z"
}, {
"token" : "06da9efd-1b73-4858-b72f-433905717038",
"amount" : 50.00,
"type" : "CREDIT",
"state" : "PENDING",
"settlement_date" : "2018-04-05T00:00:00Z",
"state_reason" : "Newly created",
"user_token" : "75680b5f-e99f-471c-b307-8d67e3f8a2e4",
"created_time" : "2018-04-05T20:37:39Z",
"last_modified_time" : "2018-04-05T20:37:39Z"
}, {
"token" : "8566bfdc-4c97-4914-bcb8-d91de960bc53",
"amount" : 50.00,
"type" : "CREDIT",
"state" : "PENDING",
"settlement_date" : "2018-04-05T00:00:00Z",
"state_reason" : "Newly created",
"business_token" : "b40685a1-55b1-499d-a79a-279c6729baa9",
"created_time" : "2018-04-05T20:37:39Z",
"last_modified_time" : "2018-04-05T20:37:39Z"
}, {
"token" : "9d3ff191-490a-4393-a8d0-c74e705b9f37",
"amount" : 50.00,
"type" : "CREDIT",
"state" : "APPLIED",
"settlement_date" : "2018-04-05T00:00:00Z",
"state_reason" : "Newly created",
"user_token" : "d93abb06-bb45-42f8-b75f-baa1c93921f0",
"created_time" : "2018-04-05T20:37:37Z",
"last_modified_time" : "2018-04-05T20:37:38Z"
} ]
}


Update deposit account

Action: PUT
Endpoint: /directdeposits/accounts/{user_or_business_token}

Update the deposit account of a user or business. Include the user_or_business_token path parameter to indicate the deposit account to update. Add the modified account details to the body of the request in JSON format. This request updates only the parameter value included with the request.

URL path parameters

Name Type Required? Description Allowable Values
user_or_business_token string Yes Identifies the owner of the deposit account to update. Existing user or business token.

Use a GET request to retrieve tokens from /users or /businesses.

Body field details

Name Type Required? Description Allowable Values
allow_immediate_credit boolean No When set to true, deposits are credited to the account immediately. When set to false, deposits will be credited to the account at 2:30 P.M. PST on the settlement date. true | false

Default: false

Sample Request

{
"allow_immediate_credit": true
}

Sample response

{
"token" : "460d40c8-1a33-436b-8e49-de895eecbff3",
"user_token" : "3f0aa078-1db7-47cf-abf4-3a7ae7cd9e20",
"account_number" : "12341059728166561",
"routing_number" : "293748000",
"allow_immediate_credit" : true
}


Retrieve deposit account

Action: GET
Endpoint: /directdeposits/accounts/{user_or_business_token}

Retrieve the deposit account and routing information for an account holder. Include the user_or_business_token path parameter to specify the deposit account to return.

This endpoint returns the account holder's deposit account number and routing number.

URL path parameters

Name Type Required? Description Allowable Values
user_or_business_token string Yes The account holder associated with the deposit account. Existing user or business token.

Use a GET request to retrieve tokens from /users or /businesses.

Sample response

{
"user_token": "bluebird_token",
"account_number": "12343054860200",
"routing_number": "293748000",
"allow_immediate_credit": false
}


Create direct deposit transition

Action: POST
Endpoint: /directdeposits/transitions

Change the state of a direct deposit.

Direct deposits can have the following states:

State Description
APPLIED The credit or debit is applied to the deposit account.
PENDING The credit or debit is ready to be applied on the settlement date; optionally, you can manually transition the credit or debit to APPLIED before the settlement date.
REVERSED If transitioned from PENDING, the credit or debit is not applied to the deposit account.

If transitioned from APPLIED during the credit or debit grace period, the credit or debit is reversed (credits are debited, debits are credited). You cannot transition a credit or debit in the APPLIED state to REVERSED after the credit or debit grace period. The length of the grace period depends on the reason code associated with the state change. See "The reason_code field" below for more information.
REJECTED The credit or debit is not applied to the deposit account. In general, this state indicates the Marqeta platform did not recognize the account or routing numbers used in the credit or debit, or the account holder receiving the credit or debit does not have an active card. You cannot transition a credit or debit in the REJECTED state to another state.

Body field details

Name Type Required? Description Allowable Values
token string No 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.
36 character max
direct_deposit_token string Yes Unique identifier of the direct deposit.

Use a GET request to retrieve tokens from /directdeposits.
36 character max
channel string No The mechanism by which the transaction was initiated. API | SYSTEM
reason string Yes Additional information about the state change. 255 character max
state string Yes Specifies the new state. APPLIED | REVERSED
reason_code string Yes A standard code describing the reason for the transition. See "The reason_code field" below.

The reason_code field

When you create a direct deposit transition, you must include a valid reason code. The following table describes supported reason codes and the grace period associated with each reason. The reason code's grace period represents the period of time in which you can reverse a previously-applied direct deposit.

Code Message Description Grace Period (calendar days)
R01 Insufficient funds Available balance does not cover the amount of the debit entry. 3
R02 Account closed Account has been closed. 3
R03 No Account/Unable to locate account Deposit account number does not map to a card holder. 3
R08 Payment Stopped Debit payment stopped. 3
R09 Uncollected funds Ledger balance exceeds debit amount. However, available balance does not. 3
R10 User advises unauthorized transaction The user indicates that the transaction is not authorized. 60
R11 Generic return code When using this code in the request, you must add text to the reason field. 3
R14 User is deceased Transaction denied because user is deceased. 3
R15 User or beneficiary is deceased User or beneficiary is deceased. 3
R16 Funds unavailable (account frozen) due to action by RDFI or other legal action A legal action has frozen the account. 3
R23 Credit entry refused by receiver The user has not authorized a credit entry to the account. 3
R29 Corporate customer advises not authorized The business indicates that the transaction is not authorized. 3

For more information about National Automated Clearing House Association (NACHA) batch files, see www.nacha.org.

Sample request

{
"token" : "019b3329-6d18-49e6-adb7-34045a4a3a89",
"channel": "API",
"reason": "Manual state change",
"direct_deposit_token" : "ff035886-5a59-4e9a-86a1-dba8a7cf9c06",
"state": "APPLIED",
"reason_code": "R11"
}

Sample response

{
"channel" : "API",
"token" : "019b3329-6d18-49e6-adb7-34045a4a3a89",
"reason" : "Manual state change",
"type" : "state.applied",
"direct_deposit_token" : "ff035886-5a59-4e9a-86a1-dba8a7cf9c06",
"transaction_token" : "677",
"state" : "APPLIED",
"reason_code" : "R11",
"created_time" : "2018-04-05T21:01:59Z"
}


Retrieve direct deposit transition

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

Retrieve a direct deposit transition. Include the token path parameter to specify the record to return.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the direct deposit transition record to retrieve. Existing direct deposit transition token.

Sample response

{
"channel" : "SYSTEM",
"token" : "72fccea3-6b70-4636-80aa-7732f3d98e7f",
"reason" : "Newly created",
"type" : "state.pending",
"direct_deposit_token" : "ff035886-5a59-4e9a-86a1-dba8a7cf9c06",
"transaction_token" : "674",
"state" : "PENDING",
"created_time" : "2018-04-05T20:37:40Z"
}


List direct deposit transitions

Action: GET
Endpoint: /directdeposits/transitions

Retrieve a list of direct deposit transition records.

This endpoint supports pagination and field filtering.

Query parameters

Name Type Required? Description Allowable Values
user_or_business_token string No The account holder for which to return transition records. Existing user or business token.

Use a GET request to retrieve tokens from /users or /businesses.
direct_deposit_token string No The direct deposit credit or debit for which to return transition records.

Use a GET request to retrieve tokens from /directdeposits.
Existing direct deposit record token.
states string No The states for which to return transition records. APPLIED | PENDING | REVERSED | REJECTED

Sample response

{
"count" : 5,
"start_index" : 0,
"end_index" : 4,
"is_more" : true,
"data" : [ {
"channel" : "SYSTEM",
"token" : "72fccea3-6b70-4636-80aa-7732f3d98e7f",
"reason" : "New credit",
"type" : "state.pending",
"direct_deposit_token" : "ff035886-5a59-4e9a-86a1-dba8a7cf9c06",
"transaction_token" : "674",
"state" : "PENDING",
"created_time" : "2018-04-05T20:37:40Z"
}, {
"channel" : "SYSTEM",
"token" : "a07a217a-4f1e-4281-abb4-954207a91814",
"reason" : "Success credit immediate",
"type" : "state.applied",
"direct_deposit_token" : "c4ec050d-3e49-4fa4-9fea-11bc18506be3",
"transaction_token" : "675",
"state" : "APPLIED",
"created_time" : "2018-04-05T20:37:40Z"
}, {
"channel" : "SYSTEM",
"token" : "56c8f7bb-2aa6-4ea5-9ecb-b78a342d4650",
"reason" : "New credit",
"type" : "state.pending",
"direct_deposit_token" : "06da9efd-1b73-4858-b72f-433905717038",
"transaction_token" : "672",
"state" : "PENDING",
"created_time" : "2018-04-05T20:37:39Z"
},{
"channel" : "SYSTEM",
"token" : "d088ba05-d683-4a31-8989-3e0aec283ab5",
"reason" : "New credit",
"type" : "state.pending",
"direct_deposit_token" : "8566bfdc-4c97-4914-bcb8-d91de960bc53",
"transaction_token" : "673",
"state" : "PENDING",
"created_time" : "2018-04-05T20:37:39Z"
}, {
"channel" : "API",
"token" : "38711d42-4286-4881-8966-45eb44d9845a",
"reason" : "transition from pending",
"type" : "state.applied",
"direct_deposit_token" : "9d3ff191-490a-4393-a8d0-c74e705b9f37",
"transaction_token" : "667",
"state" : "APPLIED",
"created_time" : "2018-04-05T20:37:38Z"
} ]
}