DOCS

New!

/

10 minute read

August 3, 2019

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 representative for more information.

Retrieve direct deposit record

Action: GET
Endpoint: /directdeposits/{token}

Get started now!

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

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

Fields Description

token

string, required

Identifies the direct deposit record to retrieve.

Allowable Values:

Existing direct deposit record token.

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

Body field details (response)

Fields Description

token

string, required

Unique identifier of the direct deposit record.

Allowable Values:

Existing direct deposit record token.

amount

decimal, required

Amount being debited or credited.

Allowable Values:

type

string, required

Whether funds are being debited from or credited to the account.

Allowable Values:

DEBIT, CREDIT

state

string, required

Current status of the direct deposit record.

Allowable Values:

PENDING, APPLIED, REVERSED, REJECTED

settlement_date

string, required

Date when the credit or debit is applied if immediate credit is not enabled.

Allowable Values:

Format yyyy-mm-ddThh:mm:ssZ

state_reason

string, required

Explanation of why the direct deposit record is in the current state.

Allowable Values:

255 char max

state_reason_code

string, required

A standard code describing the reason for the current state.

Allowable Values:

See "The reason_code field" on this page.

user_token OR business_token

string, required

Unique identifier of the user or business associated with the direct deposit record.

Allowable Values:

Existing user or business token.

standard_entry_class_code

string, required

Three-letter code identifying the type of entry.

Allowable Values:

ACK, ADV, ARC, ATX, BOC, CCD, CIE, COR, CTX, DNE, ENR, IAT, MTE, POP, POS, PPD, RCK, SHR, TEL, TRC, TRX, WEB, XCK

company_name

string, required

Name of the direct deposit originator.

Allowable Values:

16 char max

company_discretionary_data

string, required

Company-specific data provided by the direct deposit originator.

Allowable Values:

20 char max

company_identification

string, required

Alphanumeric code that identifies the direct deposit originator.

Allowable Values:

10 char max

company_entry_description

string, required

Description of the purpose of the direct deposit.

Allowable Values:

10 char max

individual_identification_number

string, required

Accounting number by which the recipient is known to the direct deposit originator.

Allowable Values:

individual_name

string, required

Identity of the direct deposit recipient.

Allowable Values:

22 char max

Sample response body

{
    "token": "00acce2b-cead-45ab-9417-f8a62326c0d5",
    "amount": 50.00,
    "type": "DEBIT",
    "state": "PENDING",
    "settlement_date": "2018-12-31T00:00:00Z",
    "state_reason": "Newly created",
    "state_reason_code": "R11",
    "user_token": "my_user",
    "standard_entry_class_code": "WEB",
    "company_name": "COMPANY_NAME",
    "company_discretionary_data": "",
    "company_identification": "9876543210",
    "company_entry_description": "PURCHASE",
    "individual_identification_number": "1234567890",
    "individual_name": "JOHN SMITH",
    "created_time": "2018-12-12T21:02:37Z",
    "last_modified_time": "2018-12-12T21:02:37Z"
}

Is this helpful?

List direct deposit records

Action: GET
Endpoint: /directdeposits

Get started now!

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

Retrieve a list of all direct deposit records.

This endpoint supports pagination and field filtering.

Query parameters

Fields Description

user_token OR business_token

string, optional

The account holder for which to return records. Pass either a user_token or business_token. Performs a non-case-sensitive match.

Allowable Values:

Existing user or business token.

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

direct_deposit_state

string, optional

Performs a case-sensitive match on the direct_deposit_state field.

Allowable Values:

PENDING, APPLIED, REVERSED, REJECTED

Sample response body

{
  "count" : 2,
  "start_index" : 0,
  "end_index" : 1,
  "is_more" : false,
  "data" : [ {
    "token" : "ff035886-5a59-4e9a-86a1-dba8a7cf9c06",
    "amount" : 50.00,
    "type" : "CREDIT",
    "state" : "PENDING",
    "settlement_date" : "2018-12-06T00:00:00Z",
    "state_reason" : "Newly created",
    "state_reason_code": "R11",
    "user_token" : "3f0aa078-1db7-47cf-abf4-3a7ae7cd9e20",
    "standard_entry_class_code": "WEB",
    "company_name": "NEW_COMPANY",
    "company_discretionary_data": "",
    "company_identification": "8765432109",
    "company_entry_description": "SALARY",
    "individual_identification_number": "2345678901",
    "individual_name": "JANE SMITH",
    "created_time" : "2018-012-05T20:37:40Z",
    "last_modified_time" : "2018-12-05T20:37:40Z"
  }, {
    "token" : "c4ec050d-3e49-4fa4-9fea-11bc18506be3",
    "amount" : 25.00,
    "type" : "DEBIT",
    "state" : "APPLIED",
    "settlement_date" : "2018-12-07T00:00:00Z",
    "state_reason" : "Successfully applied",
    "state_reason_code": "R11",
    "business_token" : "a86c1926-30ab-41fe-8c75-ba4a0baef1fd",
    "standard_entry_class_code": "WEB",
    "company_name": "COMPANY_NAME",
    "company_discretionary_data": "",
    "company_identification": "9876543210",
    "company_entry_description": "PURCHASE",
    "individual_identification_number": "1234567890",
    "individual_name": "JOHN SMITH",
    "created_time" : "2018-12-05T20:37:40Z",
    "last_modified_time" : "2018-12-07T20:37:40Z"
  } ]
}

Is this helpful?

Update deposit account

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

Get started now!

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

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

Fields Description

user_or_business_token

string, required

Identifies the owner of the deposit account to update.

Allowable Values:

Existing user or business token.

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

Body field details

Fields Description

allow_immediate_credit

boolean, optional

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.

Allowable Values:

true, false

Default value: false

Sample Request

{
    "allow_immediate_credit": true
}

Is this helpful?

Sample response body

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

Is this helpful?

Retrieve deposit account

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

Get started now!

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

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.

Note
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the card holder’s primary account number (PAN), personal identification number (PIN), and card expiration date.

URL path parameters

Fields Description

user_or_business_token

string, required

The account holder associated with the deposit account.

Allowable Values:

Existing user or business token.

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

Sample response body

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

Is this helpful?

Create direct deposit transition

Action: POST
Endpoint: /directdeposits/transitions

Get started now!

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

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

Fields Description

token

string, optional

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 character max

direct_deposit_token

string, required

Unique identifier of the direct deposit.

Use a GET request to retrieve tokens from /directdeposits.

Allowable Values:

36 character max

channel

string, optional

The mechanism by which the transaction was initiated.

Allowable Values:

API, SYSTEM

reason

string, required

Additional information about the state change.

Allowable Values:

255 character max

state

string, required

Specifies the new state.

Allowable Values:

APPLIED, REVERSED

reason_code

string, required

A standard code describing the reason for the transition.

Allowable Values:

See "The reason_code field" on this page.

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 body

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

Is this helpful?

Sample response body

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

Is this helpful?

Retrieve direct deposit transition

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

Get started now!

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

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

URL path parameters

Fields Description

token

string, required

Identifies the direct deposit transition record to retrieve.

Allowable Values:

Existing direct deposit transition token.

Sample response body

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

Is this helpful?

List direct deposit transitions

Action: GET
Endpoint: /directdeposits/transitions

Get started now!

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

Retrieve a list of direct deposit transition records.

This endpoint supports pagination and field filtering.

Query parameters

Fields Description

user_or_business_token

string, optional

The account holder for which to return transition records.

Allowable Values:

Existing user or business token.

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

direct_deposit_token

string, optional

The direct deposit credit or debit for which to return transition records.

Use a GET request to retrieve tokens from /directdeposits.

Allowable Values:

Existing direct deposit record token.

states

string, optional

The states for which to return transition records.

Allowable Values:

APPLIED, PENDING, REVERSED, REJECTED

Sample response body

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

Is this helpful?

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.