Bank Transfers

Use the /banktransfers endpoint to move funds between your program reserve account and an external account over the ACH Network.

Note: This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.

You can create the following types of transfers:

  • Push funds from your program reserve account to an external account.
  • Pull funds from your external account into your program reserve account.

You must have an existing bank account at a US bank to fund or receive funds from your program reserve account. To add an external account to the Marqeta platform, send a POST request to the /fundingsources/program/ach endpoint.

Note: To move funds within the Marqeta platform, use the /transfers endpoint.

Create ACH transfer

Action: POST
Endpoint: /banktransfers/ach

Create an ACH transfer that pushes funds into an external account or pulls funds into your program reserve account.

Body field details

Name Type Required? Description Allowable Values
funding_sources_ach_token string Yes The ACH funding source token for the external account. Existing ACH funding source token.
type enum Yes Specifies whether the ACH transfer is a push (credit) or pull (debit). PUSH | PULL
currency_code string Yes The currency of the push or pull. Default: USD
amount decimal Yes The amount to push or pull. 0.01 minimum
fees array No A comma-separated array of fee objects to charge for the ACH transfer. See Fees.
memo string No Additional text describing the ACH transfer. 99 char max
transfer_speed enum Yes Specifies how quickly to initiate the ACH transfer.

Note: Same-day transfers are limited to a maximum amount of $25,000.
STANDARD | SAME_DAY
standard_entry_class_code string Yes Three-letter code identifying the type of entry.

  • WEB - Internet-initiated entry
  • PPD - Prearranged Payment and Deposit
  • CCD - Cash Concentration and Disbursement
WEB | PPD | CCD

The status field (response only)

The status field describes the current state of the ACH transfer.

Status Description
pending The transfer is waiting to be processed.
processing The transfer is being processed by the Marqeta platform.
submitted The transfer was submitted to the bank or other financial institution, also known as the originating depository financial institution (ODFI).
returned The transfer was rejected by the bank or other financial institution.
completed The transfer completed successfully.
canceled The transfer was cancelled before being processed by the Marqeta platform.
rejected The transfer failed validation.

Sample request body

{
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PUSH",
"amount": "10.00",
"transfer_speed": "STANDARD",
"standard_entry_class_code": "WEB",
"currency_code": "USD",
"fees": ["1.00", "0.50"],
"memo": "Bank transfer"
}

Sample response body

{
"token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"amount": "10.00",
"fees": ["1.00", "0.50"],
"memo": "Bank transfer",
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"standard_entry_class_code": "WEB",
"status": "PENDING",
"transitions":
[
{
"token": "0565329e-405d-45ca-9ab4-ca0cd07eca4c",
"bank_transfer_token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"status": "PENDING",
"reason": "Created by POST call on API",
"channel": "API",
"created_time": "2019-03-20T18:32:32Z",
"last_modified_time": "2019-03-20T18:32:32Z"
}
],
"created_time": "2019-03-20T18:32:32Z",
"last_modified_time": "2019-03-20T18:32:32Z"
}


Retrieve ACH transfer

Action: GET
Endpoint: /banktransfers/ach/{token}

Retrieve a specific ACH transfer.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the ACH transfer to retrieve. Existing ACH transfer token.

Sample response body

{
"token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"amount": 100.00,
"funding_source_token": "bbaefe8f-f5d0-43f6-8576-16f562d23f3f",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"standard_entry_class_code": "WEB",
"status": "PROCESSING",
"transitions":
[
{
"token": "1d208bf9-8439-4b35-9c43-6d5bc74995c7",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PENDING",
"reason": "Created by POST call on API",
"channel": "API",
"created_time": "2019-03-22T18:01:00Z",
"last_modified_time": "2019-03-22T18:01:00Z"
},
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "01",
"channel": "API",
"created_time": "2019-03-22T18:01:17Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}
],
"created_time": "2019-03-22T18:01:00Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}


List ACH transfers

Action: GET
Endpoint: /banktransfers/ach

Retrieve a list of all ACH transfers.

Query parameters

Name Type Required? Description Allowable Values
user_token
OR
business_token
string No Identifies the user or business whose ACH transfers you want to list. Existing user or business token.
funding_source_token string No Identifies the funding source for which you want to list associated ACH transfers. Existing funding source token.
status string No Current state of the ACH transfer. pending | processing | submitted | returned | completed | cancelled | rejected

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"amount": "10.00",
"fees": ["1.00", "0.50"],
"memo": "Bank transfer",
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"standard_entry_class_code": "WEB",
"status": "PENDING",
"transitions":
[
{
"token": "0565329e-405d-45ca-9ab4-ca0cd07eca4c",
"bank_transfer_token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"status": "PENDING",
"reason": "Created by POST call on API",
"channel": "API",
"created_time": "2019-03-20T18:32:32Z",
"last_modified_time": "2019-03-20T18:32:32Z"
}
],
"created_time": "2019-03-20T18:32:32Z",
"last_modified_time": "2019-03-20T18:32:32Z"
},
{
"token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"amount": 100.00,
"funding_source_token": "bbaefe8f-f5d0-43f6-8576-16f562d23f3f",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"standard_entry_class_code": "WEB",
"status": "PROCESSING",
"transitions":
[
{
"token": "1d208bf9-8439-4b35-9c43-6d5bc74995c7",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PENDING",
"reason": "Created by POST call on API",
"channel": "API",
"created_time": "2019-03-22T18:01:00Z",
"last_modified_time": "2019-03-22T18:01:00Z"
},
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "01",
"channel": "API",
"created_time": "2019-03-22T18:01:17Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}
],
"created_time": "2019-03-22T18:01:00Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}
]
}


Create an ACH transfer transition

Action: POST
Endpoint: /banktransfers/ach/transitions

Create an ACH transfer transition that updates the status of an ACH transfer.

Each ACH transfer has a lifecycle of statuses, as shown in the following diagram:

Note: You can create ACH transfer transitions in the sandbox environment. However, Marqeta transitions ACH transfers through their lifecycle in the production environment.

Body field details

Name Type Required? Description Allowable Values
bank_transfer_token string Yes Token of the ACH transfer you want to transition. Existing ACH transfer token.
status string Yes New state of the ACH transfer. pending | processing | submitted | returned | completed | cancelled | rejected
reason string Yes Description of why the ACH transfer status was updated. 255 char max
channel string Yes Mechanism by which the transaction was initiated. API | SYSTEM

Sample request body

{
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "01",
"channel": "API"
}

Sample response body

{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "01",
"channel": "API",
"created_time": "2019-03-22T18:01:17Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}


Retrieve an ACH transfer transition

Action: GET
Endpoint: /banktransfers/ach/transitions/{token}

Retrieve a specific ACH transfer transition.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the ACH transfer transition to retrieve. Existing ACH transfer transition token.

Sample response body

{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "01",
"channel": "API",
"created_time": "2019-03-22T18:01:17Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}


List ACH transfer transitions

Action: GET
Endpoint: /banktransfers/ach/transitions

Retrieve a list of all ACH transfer transitions for a given ACH transfer.

Query parameters

Name Type Required? Description Allowable Values
bank_transfer_token string No Identifies the ACH transfer for which you want to list transitions. Existing ACH transfer token.
status string No Current state of the ACH transfer. pending | processing | submitted | returned | completed | cancelled | rejected

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "1d208bf9-8439-4b35-9c43-6d5bc74995c7",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PENDING",
"reason": "Created by POST call on API",
"channel": "API",
"created_time": "2019-03-22T18:01:00Z",
"last_modified_time": "2019-03-22T18:01:00Z"
},
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "01",
"channel": "API",
"created_time": "2019-03-22T18:01:17Z",
"last_modified_time": "2019-03-22T18:01:17Z"
}
]
}