DOCS

New!

/

5 minute read

August 2, 2019

Program Reserve Funding via ACH (Beta)

Use the /banktransfers endpoint to move funds between your program reserve account and an external account over the ACH Network. This kind of bank transfer is also known as ACH origination.

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

Fields Description

funding_sources_ach_token

string, required

The ACH funding source token for the external account.

Allowable Values: Existing ACH funding source token.

type

enum, required

Specifies whether the ACH transfer is a push (credit) or pull (debit).

Allowable Values: PUSH, PULL

currency_code

string, required

The currency of the push or pull.

Allowable Values: Default value: USD

amount

decimal, required

The amount to push or pull.

Allowable Values: 0.01 minimum

fees

array, optional

A comma-separated array of fee objects to charge for the ACH transfer.

Allowable Values: See Fees.

memo

string, optional

Additional text describing the ACH transfer.

Allowable Values: 99 char max

transfer_speed

enum, required

Specifies how quickly to initiate the ACH transfer.

Note
Same-day transfers are limited to a maximum amount of $25,000.

Allowable Values: STANDARD, SAME_DAY

standard_entry_class_code

string, required

Three-letter code identifying the type of entry.

  • WEB - Internet-initiated entry

  • PPD - Prearranged Payment and Deposit

  • CCD - Cash Concentration and Disbursement

Allowable Values: 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"
}

Is this helpful?

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

Is this helpful?

Retrieve ACH transfer

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

Retrieve a specific ACH transfer.

URL path parameters

Fields Description

token

string, required

The token of the ACH transfer to retrieve.

Allowable Values: 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"
}

Is this helpful?

List ACH transfers

Action: GET
Endpoint: /banktransfers/ach

Retrieve a list of all ACH transfers.

Query parameters

Fields Description

user_token OR business_token

string, optional

Identifies the user or business whose ACH transfers you want to list.

Allowable Values: Existing user or business token.

funding_source_token

string, optional

Identifies the funding source for which you want to list associated ACH transfers.

Allowable Values: Existing funding source token.

status

string, optional

Current state of the ACH transfer.

Allowable Values: 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"
    }
  ]
}

Is this helpful?

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:

Bank transfer lifecycle

Is this helpful?

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

Fields Description

bank_transfer_token

string, required

Token of the ACH transfer you want to transition.

Allowable Values: Existing ACH transfer token.

status

string, required

New state of the ACH transfer.

Allowable Values: pending, processing, submitted, returned, completed, cancelled, rejected

reason

string, required

Description of why the ACH transfer status was updated.

Allowable Values: 255 char max

channel

string, required

Mechanism by which the transaction was initiated.

Allowable Values: API, SYSTEM

Sample request body

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

Is this helpful?

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

Is this helpful?

Retrieve an ACH transfer transition

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

Retrieve a specific ACH transfer transition.

URL path parameters

Fields Description

token

string, required

The token of the ACH transfer transition to retrieve.

Allowable Values: 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"
}

Is this helpful?

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

Fields Description

bank_transfer_token

string, optional

Identifies the ACH transfer for which you want to list transitions.

Allowable Values: Existing ACH transfer token.

status

string, optional

Current state of the ACH transfer.

Allowable Values: 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"
    }
  ]
}

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.