> ## Documentation Index > Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Direct Deposit > The Marqeta platform's direct deposit feature enables third parties to credit or debit the general purpose account of a Marqeta account holder. Resources to create and maintain a digital account throughout its lifecycle are here as well. export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => { const METHOD_STYLES = { GET: { bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20", text: "mint-text-green-700 dark:mint-text-green-400", border: "mint-border-green-300 dark:mint-border-green-700" }, POST: { bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20", text: "mint-text-blue-700 dark:mint-text-blue-400" }, PUT: { bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20", text: "mint-text-yellow-700 dark:mint-text-yellow-400" }, PATCH: { bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20", text: "mint-text-orange-700 dark:mint-text-orange-400" }, DELETE: { bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20", text: "mint-text-red-700 dark:mint-text-red-400" }, API: { bg: "mint-bg-black", text: "mint-text-white" } }; const MethodBadge = ({method}) => { const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET; return {method?.toUpperCase()} ; }; const content =
{}
{}

{title}

{children &&

{children}

}
; if (!href) return content; return {content} ; }; Hidden **Note**\ We are pleased to announce that the Marqeta platform now offers [ACH Receiving](/core-api/ach-receiving/), a refreshed version of the API that enables third parties to credit or debit the general purpose account (GPA) of a Marqeta account holder. The API version featured on this page is being withdrawn and will not be used for new card programs. Existing card programs have already transitioned to ACH Receiving. Contact your Marqeta representative for more information.

Retrieve direct deposit record

**Action:** `GET`\ **Endpoint:** `/directdeposits/{token}` Retrieves 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 | Unique identifier of the direct deposit record to retrieve.

**Allowable Values:**

Existing direct deposit record token.

Send a `GET` request to `/directdeposits` to retrieve direct deposit tokens. |

Response body

| Fields | Description | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | token

string

Returned | Unique identifier of the direct deposit record.

**Allowable Values:**

Existing direct deposit record token. | | amount

decimal

Returned | Amount being debited or credited.

**Allowable Values:**

Existing amount in 0.00 decimal format. | | type

string

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

**Allowable Values:**

`DEBIT`, `CREDIT` | | state

string

Returned | Current status of the direct deposit record.

**Allowable Values:**

`PENDING`, `APPLIED`, `REVERSED`, `REJECTED` | | settlement\_date

string

Returned | Date when the credit or debit is applied.

**Allowable Values:**

Format: yyyy-mm-ddThh:mm:ssZ | | state\_reason

string

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

**Allowable Values:**

255 char max | | state\_reason\_code

string

Returned | A standard code describing the reason for the current state.

**Allowable Values:**

See ACHR return reason codes for the full list of supported codes and the grace period associated with each. | | direct\_deposit\_account\_token

string

Returned | Unique identifier of the affected deposit account.

**Allowable Values:**

36 char max | | user\_token OR business\_token

string

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

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

Returned | Name of the direct deposit originator.

**Allowable Values:**

16 char max | | company\_discretionary\_data

string

Returned | Company-specific data provided by the direct deposit originator.

**Allowable Values:**

20 char max | | company\_identification

string

Returned | Alphanumeric code that identifies the direct deposit originator.

**Allowable Values:**

10 char max | | company\_entry\_description

string

Returned | Description of the purpose of the direct deposit.

**Allowable Values:**

10 char max | | individual\_identification\_number

string

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

**Allowable Values:**

15 or 22 char max, depending on the value of `standard_entry_class_code`. | | individual\_name

string

Returned | Identity of the direct deposit recipient.

**Allowable Values:**

22 char max |

Sample response body

```json JSON lines wrap theme={null} { "token": "00acce2b-cead-45ab-9417-f8a62326c0d5", "amount": 50.00, "type": "DEBIT", "state": "PENDING", "settlement_date": "2019-12-31T00:00:00Z", "state_reason": "Newly created", "state_reason_code": "R11", "direct_deposit_account_token": "7e9d9519-eb07-4ccd-9a6f-055547da326c", "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": "2019-12-12T21:02:37Z", "last_modified_time": "2019-12-12T21:02:37Z" } ```

List direct deposit records

**Action:** `GET`\ **Endpoint:** `/directdeposits` Retrieves a list of all direct deposit records for your program. This endpoint supports [pagination](/core-api/sorting-and-pagination/) and [field filtering](/core-api/field-filtering/).

Query parameters

| Fields | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | user\_token OR business\_token

string

Optional | 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.

Send 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` | | count

integer

Optional | The number of direct deposit records to retrieve.

**Allowable Values:**

Up to 100 records


**Default value:**
5 | | start\_index

integer

Optional | Specifies the sort order index from which to begin returning direct deposit records.

**Allowable Values:**

Any integer | | start\_settlement\_date

string

Optional | The beginning of the settlement date range from which to return direct deposit records.

**Allowable Values:**

Format: yyyy-mm-dd | | end\_settlement\_date

string

Optional | The end of the settlement date range from which to return direct deposit records.

**Allowable Values:**

Format: yyyy-mm-dd | | sort\_by

string

Optional | The fields by which to sort.


Use any fields in the view schema, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix a field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.

**Allowable Values:**

Any field in the schema |

Sample response body

```json JSON expandable lines wrap theme={null} { "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": "2019-12-06T00:00:00Z", "state_reason": "Newly created", "state_reason_code": "R11", "direct_deposit_account_token": "7e9d9519-eb07-4ccd-9a6f-055547da335c", "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": "2019-012-05T20:37:40Z", "last_modified_time": "2019-12-05T20:37:40Z" }, { "token": "c4ec050d-3e49-4fa4-9fea-11bc18506be3", "amount": 25.00, "type": "DEBIT", "state": "APPLIED", "settlement_date": "2019-12-07T00:00:00Z", "state_reason": "Successfully applied", "state_reason_code": "R11", "direct_deposit_account_token": "7e9d9519-eb07-4ccd-9a6f-055547da326c", "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": "2019-12-05T20:37:40Z", "last_modified_time": "2019-12-07T20:37:40Z" } ] } ```

Create direct deposit transition

**Action:** `POST`\ **Endpoint:** `/directdeposits/transitions` Changes 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. | | `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 ACHR return reason codes for the full list of supported codes and the grace period associated with each.

**NOTE:** You can only return *credit* entries using the R23 reason code. Attempting to return a debit entry by transitioning it to `REVERSED` using this endpoint would result in a `400` HTTP error code and the message, "R23 can only be used when returning a credit entry refused by the receiver." | | `REJECTED` | The credit or debit is not applied to the deposit account. In general, this state indicates that the Marqeta platform did not recognize the account or routing numbers used in the credit or debit, or that 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. |

The reason\_code field

When you create a direct deposit transition and change the state of a direct deposit, you must include a valid reason code to explain why the transition was made (unless you are transitioning a direct deposit to the `APPLIED` state). These reason codes are only used for ACH processing, and are not shared outside the ACH network. 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 during which you can reverse a previously applied direct deposit. The grace period begins after the settlement date. **Note**\ Unless stated otherwise, the grace period is calculated using banking days, which excludes US holidays and weekends. For example, a transition created on the Friday before Memorial Day would have a grace period until the following Wednesday, since the Monday is a holiday and Saturday and Sunday are non-banking days. | Code | Message | Description | Grace Period | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | R01 | Insufficient funds | Available balance is not sufficient to cover the amount of the debit entry. | 2 days | | R02 | Account closed | Account has been closed. | 2 days | | R03 | No account

Unable to locate account

Inactive cardholder | Account number is a valid structure, but does not correspond to the user (or the cardholder is inactive). Also used when the account number designated is not associated with an existing account. | 2 days | | R06 | Returned per ODFI request | The Originating Depository Financial Institution (ODFI) has requested that the Receiving Depository Financial Institution (RDFI) return an Erroneous Entry, or a credit entry has originated without the originator’s authorization. | 60 days | | R08 | Payment stopped | The receiver has placed a stop payment order on this debit entry. | 2 days | | R09 | Uncollected funds | A sufficient ledger balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit entry. | 2 days | | R10 | User advises of an unauthorized, improper, ineligible, or incomplete transaction.

User advises that the originator is unknown to the receiver and/or the originator is not authorized to debit the receiver’s account. | The user indicates that the transaction is unauthorized, improper, ineligible, or incomplete.

The receiver does not know the identity of the originator and/or the originator is not authorized by the receiver to debit the receiver’s account. | 60 days | | R11 | Customer advises entry not in accordance with the terms of the authorization | The RDFI has been notified by the receiver that the originator and receiver have a relationship and an authorization to debit exists. However, an error in the payment means that the entry does not conform to the terms of the authorization (e.g. different amount than authorized, earlier than authorized, debit entry improperly reinitiated).

**NOTE:** When sending this reason code, the RDFI must include Addenda field information to specify the reason for the return, such as "exceeds dollar amount" or the stale date. | 60 days | | R14 | Representative payee is deceased or unable to continue in that capacity | The representative payee is a person or institution authorized to accept entries on behalf of one or more other persons, such as legally incapacitated adults or minor children. The transaction is denied because the representative payee is either deceased or unable to continue in that capacity. The beneficiary is not deceased. | 2 days | | R15 | Beneficiary or account holder is deceased | The transaction is denied because the beneficiary and/or the account holder (other than the representative payee) is deceased. | 2 days | | R16 | Account frozen/returned per OFAC instruction | Access to the account has been restricted by the RDFI or by legal action, or OFAC has instructed the RDFI or gateway to return the entry. | 2 days | | R17 | Suspicious or questionable transaction | The RDFI believes that the entry containing invalid account information was initiated under questionable circumstances.

**NOTE:** An RDFI who chooses to use R17 must add the description `"QUESTIONABLE"` to the Addenda Information field of the return. This will guide the ODFI when differentiating between suspicious returns and returns with routine account number issues. | 2 days | | R20 | Non-transaction account | The ACH entry is destined for a non-transaction account, which is an account against which transactions are prohibited or limited. | 2 days | | R23 | Credit entry refused by receiver | Any credit that is refused by the receiver may be returned by the RDFI to the originator. | 60 days, starting from when the receiver notifies the program of the intention to decline the funds | | R24 | Duplicate entry | The RDFI has received what appears to be a duplicate entry: the date, dollar amount, trace number, and other data matches another transaction. | 2 days | | R29 | Corporate customer advises not authorized | The RDFI has been notified by the receiver (non-consumer) that a specific entry has not been authorized by the receiver. | 2 days | For more information about National Automated Clearing House Association (NACHA) batch files, see [www.nacha.org](https://www.nacha.org).

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 char max | | direct\_deposit\_token

string

Required | Unique identifier of the direct deposit.

Send a `GET` request to retrieve tokens from `/directdeposits`.

**Allowable Values:**

36 char max | | channel

string

Required | The mechanism by which the transaction was initiated.

**Allowable Values:**

`API`, `SYSTEM` | | state

string

Required | Specifies the new state.

**Allowable Values:**

`APPLIED`, `REVERSED` | | reason

string

Required | Explanation of why the account transitions record was created.

**Allowable Values:**

255 char max | | reason\_code

string

Required | A standard code describing the reason for the transition.

**NOTE:** The reason code is optional when transitioning a direct deposit to the `APPLIED` state. It is required for the `REVERSED` state.

**Allowable Values:**

See ACHR return reason codes for the full list of supported codes and the grace period associated with each. |

Sample request body

```json JSON lines wrap theme={null} { "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 body

```json JSON lines wrap theme={null} { "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": "2020-04-05T21:01:59Z" } ```

Retrieve direct deposit transition

**Action:** `GET`\ **Endpoint:** `/directdeposits/transitions/{token}` Retrieves 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

```json JSON lines wrap theme={null} { "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": "2020-04-05T20:37:40Z" } ```

List direct deposit transitions

**Action:** `GET`\ **Endpoint:** `/directdeposits/transitions` Retrieves a list of direct deposit transition records. This endpoint supports [pagination](/core-api/sorting-and-pagination/) and [field filtering](/core-api/field-filtering/).

Query parameters

| Fields | Description | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | user\_or\_business\_token

string

Optional | Account holder whose transition records you want to return.

**Allowable Values:**

Existing user or business token.

Send 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.

Send 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. To list transition records for more than one state, create a comma-delimited list.

**Allowable Values:**

`APPLIED`, `PENDING`, `REVERSED`, `REJECTED` |

Sample response body

```json JSON expandable lines wrap theme={null} { "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": "2020-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": "2020-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": "2020-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": "2020-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": "2020-04-05T20:37:38Z" } ] } ```