/

20 minute read

September 25, 2020

Direct Deposits (Beta)

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

You can change the state of a direct deposit account.

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

Create direct deposit account

Action: POST
Endpoint: /depositaccounts

Develop Now!

Sign in and use your sandbox to access the API Explorer

Creates a new direct deposit account for a user or business. An issued card—at either the parent or the child level—is required before creating an account.

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

Query parameters

Fields Description

token

string
Optional

Unique identifier of the direct 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 direct deposit account. Pass either a user_token or business_token. Performs a non-case-sensitive match.

Allowable Values:

Existing user or business token.

type

string
Optional

Type of direct deposit account being created.

Allowable Values:

DEPOSIT_ACCOUNT, CHECKING

Default value:
DEPOSIT_ACCOUNT

Note
This field is not returned in the response.

Body field details (response)

Fields Description

account_number

string
Returned

Account number assigned to the direct deposit account.

Allowable Values:

13 char max

direct_deposit_account_token

string
Returned

The unique identifier of the direct deposit account.

Allowable Values:

32 char max

routing_number

string
Returned

Routing number assigned to the direct deposit account.

Allowable Values:

9 char max

token

string
Returned

Unique identifier of the direct deposit account.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

User or business to whom the direct deposit account belongs.

Allowable Values:

Existing user or business token.

state

string
Returned

Status of the direct deposit account.

Allowable Values:

ACTIVE

created_time

string
Returned

Date and time when the direct deposit account was created.

Allowable Values:

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

last_modified_time

string
Returned

Date and time when the direct deposit account was last modified.

Allowable Values:

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

Sample request body

{
  "user_token": "bd6772dc-3ab9-4014-8ef1-fa0843bf5d0d"
}

Is this helpful?

Sample response body

{
  "account_number": "2401870493365",
  "routing_number": "041285663",
  "token": "c39fc2d0-d0b7-452c-9e88-4d17099114c3",
  "direct_deposit_account_token": "a1652a11-490b-4521-ab49-90aaff7924f40",
  "user_token": "bd6772dc-3ab9-4014-8ef1-fa0843bf5d0d",
  "state": "ACTIVE",
  "created_time": "2019-10-08T00:12:59Z",
  "last_modified_time": "2019-10-08T00:12:59Z"
}

Is this helpful?

Retrieve direct deposit account

Action: GET
Endpoint: /depositaccounts/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

URL path parameters

Fields Description

token

string
Returned

Token of the direct deposit account.

Allowable Values:

Existing direct deposit account token.

Body field details (response)

Fields Description

account_number

string
Returned

Account number assigned to the direct deposit account.

Allowable Values:

13 or 17 char max

direct_deposit_account_token

string
Returned

The unique identifier of the direct deposit account.

Allowable Values:

32 char max

routing_number

string
Returned

Routing number assigned to the direct deposit account.

Allowable Values:

9 char max

token

string
Returned

Unique identifier of the direct deposit account.

Allowable Values:

36 char max

user_token

string
Returned

User associated with the direct deposit account.

Allowable Values:

Existing user token

state

string
Returned

Status of the direct deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

created_time

string
Returned

Date and time when the direct deposit account was created.

Allowable Values:

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

last_modified_time

string
Returned

Date and time when the direct deposit account was last modified.

Allowable Values:

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

Sample response body

{
  "account_number": "2401534763971",
  "routing_number": "041815663",
  "token": "a11eecf9-0bde-4e9c-ac13-723f12a09cb3",
  "direct_deposit_account_token": "b9902fff-334a-c3c7-49ba-345fbb7924f4",
  "user_token": "bd5472cc-3cd9-4004-8ef1-fa0743bf5d0d",
  "state": "ACTIVE",
  "created_time": "2019-09-17T23:46:19Z",
  "last_modified_time": "2019-09-17T23:46:19Z"
}

Is this helpful?

List direct deposit accounts

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieves a list of all the direct 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 direct deposit accounts you want to retrieve.

Allowable Values:

Existing user or business token.

Query parameters

Fields Description

type

string
Optional

Type of direct deposit account you want to view in the list of returned accounts.

Allowable Values:

DEPOSIT_ACCOUNT, CHECKING

Note
This field is not returned in the response.

Body field details (response)

Fields Description

account_number

string
Returned

Account number assigned to the direct deposit account.

Allowable Values:

13 or 17 char max

direct_deposit_account_token

string
Returned

The unique identifier of the direct deposit account.

Allowable Values:

32 char max

routing_number

string
Returned

Routing number assigned to the direct deposit account.

Allowable Values:

9 char max

token

string
Returned

Unique identifier of the direct deposit account.

Allowable Values:

36 char max

user_token OR business_token

string
Returned

User associated with the direct deposit account.

Allowable Values:

Existing user token

state

string
Returned

Status of the direct deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

created_time

string
Returned

Date and time when the direct deposit account was created.

Allowable Values:

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

last_modified_time

string
Returned

Date and time when the direct deposit account was last modified.

Allowable Values:

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

Sample request body

{
  "type": "CHECKING"
}

Is this helpful?

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "account_number": "2403570493575",
      "routing_number": "041215623",
      "token": "c39fc2d0-d0b7-452c-9e88-4d17099114c3",
      "direct_deposit_account_token": "4e7953ba-0be5-4a85-996f-e24d7763552f",
      "user_token": "bd6773cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "state": "ACTIVE",
      "created_time": "2019-10-08T00:12:59Z",
      "last_modified_time": "2019-10-08T00:12:59Z"
    },
    {
      "account_number": "2401568763971",
      "routing_number": "041215663",
      "token": "a11eecf9-0bde-4e9c-ac13-723f12a09cb3",
      "direct_deposit_account_token": "4e7953ba-0ce1-90a1-56ab-2569ff433330f",
      "user_token": "bd6773cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "state": "ACTIVE",
      "created_time": "2019-09-17T23:46:19Z",
      "last_modified_time": "2019-09-17T23:46:19Z"
    }
  ]
}

Is this helpful?

Look up user by direct deposit account

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

URL path parameters

Fields Description

account_number

string
Required

Direct deposit account number of the user you are looking up.

Allowable Values:

Existing 13- or 17-digit direct deposit account account number.

Sample response body

{
  "token" : "03cf3266-1e6c-43aa-833e-447d34e5ce26",
  "active" : true,
  "honorific" : "Mr.",
  "gender" : "M",
  "first_name" : "John",
  "last_name" : "Smith",
  "address1" : "6201 Doyle Street",
  "city" : "Emeryville",
  "state" : "CA",
  "zip" : "94607",
  "country" : "USA",
  "uses_parent_account" : false,
  "corporate_card_holder" : false,
  "passport_number" : "1234567890",
  "id_card_number" : "id1234567890",
  "nationality" : "USA",
  "ip_address" : "192.393.394.39",
  "created_time" : "2020-04-29T21:30:45Z",
  "last_modified_time" : "2020-04-29T21:30:45Z",
  "metadata" : { },
  "account_holder_group_token" : "DEFAULT_AHG",
  "status" : "ACTIVE",
  "birth_date" : "1988-02-29",
  "passport_expiration_date" : "2021-06-29",
  "id_card_expiration_date" : "2022-04-22"
}

Is this helpful?

Create direct deposit account transition

Action: POST
Endpoint: /depositaccounts/transitions

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

Note
Accounts in the TERMINATED state cannot be transitioned to the ACTIVE or SUSPENDED states.

Query parameters

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

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

reason

string
Optional

Explanation of why the account transitions record was created.

Allowable Values:

255 char max

Body field details (response)

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:

Existing user or business token.

account_token

string
Returned

Unique identifier of the direct deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the direct deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

channel

string
Returned

Channel associated with the account transitions record.

Allowable Values:

API, IVR, FRAUD, ADMIN, 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 direct deposit transition was created.

Allowable Values:

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

Sample request body

{
  "channel": "API",
  "account_token": "bf344baf-054b-420a-852f-cbedb3413b37",
  "state": "SUSPENDED"
}

Is this helpful?

Sample response body

{
  "token": "a4e1237b-c335-4e39-acb7-bf942b2751fe",
  "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
  "account_token": "bf344baf-054b-420a-852f-cbedb3413b37",
  "state": "SUSPENDED",
  "channel": "API",
  "created_time": "2019-10-15T20:27:50Z"
}

Is this helpful?

Retrieve direct deposit account transition

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieves the specified account transition.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the account transitions record.

Allowable Values:

36 char max

Body field details (response)

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:

Existing user or business token.

account_token

string
Returned

Unique identifier of the direct deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the account transitions record.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

channel

string
Returned

Channel associated with the account transitions record.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

string
Returned

Date and time when the account transitions record was created.

Allowable Values:

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

Sample request body

{
  "account_token": "bf377baf-054b-420a-852f-cbedb3413b37"
}

Is this helpful?

Sample response body

{
  "token": "181033a3-3bd7-47b2-9f07-20fbfa053987",
  "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
  "account_token": "bf377baf-054b-420a-852f-cbedb3413b37",
  "state": "SUSPENDED",
  "channel": "API",
  "created_time": "2019-10-18T19:48:35Z"
}

Is this helpful?

Retrieve all direct deposit account transitions

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieves a list of all account transitions associated with the specified user or business.

This endpoint supports pagination and field filtering.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the account transitions record.

Allowable Values:

36 char max

Body field details (response)

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 whose account transitions you want to retrieve.

Allowable Values:

Existing user or business token.

account_token

string
Returned

Unique identifier of the direct deposit account.

Allowable Values:

36 char max

state

string
Returned

Status of the direct deposit account.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

channel

string
Returned

Channel associated with the account transitions record.

Allowable Values:

API, IVR, FRAUD, ADMIN, 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:

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

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "2de542ce-b168-4640-a17d-4701439b875d",
      "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "account_token": "bf377baf-054b-420a-852f-cbedb3413b37",
      "state": "ACTIVE",
      "channel": "IVR",
      "created_time": "2019-10-15T20:32:45Z"
    },
    {
      "token": "8435b916-6fc9-4d60-b234-ae68e7addc4b",
      "user_token": "bd6772cc-3cd9-4004-8ef1-fa0743bf5d0d",
      "account_token": "c39fc2d0-d0b7-452c-9e88-4d17099114c3",
      "state": "ACTIVE",
      "channel": "SYSTEM",
      "reason": "CREATED DDA",
      "created_time": "2019-10-08T00:12:59Z"
    }
  ]
}

Is this helpful?

Retrieve direct deposit record

Action: GET
Endpoint: /directdeposits/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

Identifies the direct deposit record to retrieve.

Allowable Values:

Existing direct deposit record token.

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

Body field details (response)

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 The reason_code field on this page.

direct_deposit_account_token

string
Returned

Unique identifier of the affected direct 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:

individual_name

string
Returned

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",
    "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": "2018-12-12T21:02:37Z",
    "last_modified_time": "2018-12-12T21:02:37Z"
}

Is this helpful?

List direct deposit records

Action: GET
Endpoint: /directdeposits

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieves 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

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-ddThh:mm:ssZ

end_settlement_date

string
Optional

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

Allowable Values:

Format yyyy-mm-ddThh:mm:ssZ

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

{
  "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",
    "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" : "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",
    "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" : "2018-12-05T20:37:40Z",
    "last_modified_time" : "2018-12-07T20:37:40Z"
  } ]
}

Is this helpful?

Create direct deposit transition

Action: POST
Endpoint: /directdeposits/transitions

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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 other states, including REVERSED.

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 to explain why the transition to another state 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.

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

R04

Invalid account number structure

The account number structure is not valid.

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

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 in order to differentiate between suspicious returns and returns with routine account number issues.

2 days

R23

Credit entry refused by receiver

Any credit that is refused by the receiver may be returned by the RDFI.

2 days

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}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieves a list of direct deposit transition records.

This endpoint supports pagination and 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.

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.