Funding via ACH (Beta)
Use the /banktransfers endpoint to move funds between your program funding or cardholder 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 funding or cardholder account to an external account.
-
Pull funds from your external account into your program funding or cardholder account.
You must have an existing bank account at a US bank to fund or receive funds from your Marqeta account.
To add an external program funding source account to the Marqeta platform, send a POST request to the /fundingsources/program/ach endpoint to PUSH or PULL money from or to the Program Funding Account.
To add an external account holder funding source account to the Marqeta platform, send a POST request to the /fundingsources/ach endpoint to PUSH or PULL money from or to the Cardholder Account.
For more information on ACH funding, see ACH Origination.
Create ACH transfer
Copy section link
Action: POST
Endpoint: /banktransfers/ach
Create an ACH transfer that pushes funds to an external account or pulls funds into your program funding account.
Request body
Copy section link
Create bank transfer request model
| Fields | Description |
|---|---|
amount
decimal
|
Amount to push or pull. Allowable Values: 0.01 min |
currency_code
string
|
Currency of the push or pull. Allowable Values: Valid alpha-3 ISO 4217 currency code Default value: |
funding_source_token
string
|
ACH funding source token for the external account. Allowable Values: 36 char max Existing ACH funding source token. |
memo
string
|
Additional text describing the ACH transfer. Allowable Values: 255 char max |
standard_entry_class_code
string
|
Three-letter code identifying the type of entry.
Allowable Values:
|
statement_descriptor
string
|
Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
token
string
|
Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
transfer_speed
string
|
Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values:
|
type
string
|
Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
amount
decimal
|
Amount to push or pull. Allowable Values: 0.01 min |
batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
currency_code
string
|
Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
funding_source_token
string
|
ACH funding source token for the external account. Allowable Values: 36 char max |
last_modified_time
datetime
|
Date and time when the ACH transfer was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
memo
string
|
Additional text describing the ACH transfer. Allowable Values: 99 char max |
return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
standard_entry_class_code
string
|
Three-letter code identifying the type of entry.
Allowable Values:
|
statement_descriptor
string
|
Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
status
string
|
New state of the ACH transfer. Allowable Values:
|
token
string
|
Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
transfer_speed
string
|
Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values:
|
transitions
array of objects
|
Array of ACH transfer transition objects. Allowable Values: Valid array of one or more |
transitions[].bank_transfer_token
string
|
Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
transitions[].batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
transitions[].channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
transitions[].created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
transitions[].last_modified_time
datetime
|
Date and time when the ACH transfer was last modified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
transitions[].program_reserve_token
string
|
Not currently used. Allowable Values: 36 char max |
transitions[].reason
string
|
Explanation of why the transition is being made, for example "Created by POST call on API". Returned if this information was supplied when the transition was originally created. Allowable Values: 255 char max |
transitions[].return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
transitions[].return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
transitions[].status
string
|
New state of the ACH transfer. Allowable Values:
|
transitions[].token
string
|
Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
transitions[].transaction_jit_token
string
|
Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
transitions[].transaction_token
string
|
Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
type
string
|
Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values:
|
List ACH transfers
Copy section link
Action: GET
Endpoint: /banktransfers/ach
Retrieve a list of all ACH transfers.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources to retrieve. Allowable Values: 1-10 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
user_token
string
|
Unique identifier of the user resource. Allowable Values: Existing user token |
business_token
string
|
Unique identifier of the business resource. Allowable Values: Existing business token |
funding_source_token
string
|
Unique identifier of the funding source. Allowable Values: Existing |
statuses
string
|
Comma-delimited list of bank transfer statuses. Allowable Values:
|
sort_by
string
|
Field on which to sort Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
expand
string
|
Returns the full funding source object when Allowable Values:
|
funding_source_type
string
|
Funding source type to filter. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
Array of ACH transfer objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more ACH transfer transition objects |
data[].amount
decimal
|
Amount to push or pull. Allowable Values: 0.01 min |
data[].batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
data[].created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].currency_code
string
|
Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
data[].funding_source_token
string
|
ACH funding source token for the external account. Allowable Values: 36 char max |
data[].last_modified_time
datetime
|
Date and time when the ACH transfer was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].memo
string
|
Additional text describing the ACH transfer. Allowable Values: 99 char max |
data[].return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
data[].return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
data[].standard_entry_class_code
string
|
Three-letter code identifying the type of entry.
Allowable Values:
|
data[].statement_descriptor
string
|
Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
data[].status
string
|
New state of the ACH transfer. Allowable Values:
|
data[].token
string
|
Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
data[].transfer_speed
string
|
Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values:
|
data[].transitions
array of objects
|
Array of ACH transfer transition objects. Allowable Values: Valid array of one or more |
data[].transitions[].bank_transfer_token
string
|
Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
data[].transitions[].batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
data[].transitions[].channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
data[].transitions[].created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].transitions[].last_modified_time
datetime
|
Date and time when the ACH transfer was last modified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].transitions[].program_reserve_token
string
|
Not currently used. Allowable Values: 36 char max |
data[].transitions[].reason
string
|
Explanation of why the transition is being made, for example "Created by POST call on API". Returned if this information was supplied when the transition was originally created. Allowable Values: 255 char max |
data[].transitions[].return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
data[].transitions[].return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
data[].transitions[].status
string
|
New state of the ACH transfer. Allowable Values:
|
data[].transitions[].token
string
|
Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
data[].transitions[].transaction_jit_token
string
|
Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
data[].transitions[].transaction_token
string
|
Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
data[].type
string
|
Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values:
|
end_index
integer
|
Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Retrieve ACH transfer
Copy section link
Action: GET
Endpoint: /banktransfers/ach/{token}
Retrieve a specific ACH transfer.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the bank transfer. Allowable Values: Existing bank transfer token |
Response body
Copy section link
| Fields | Description |
|---|---|
amount
decimal
|
Amount to push or pull. Allowable Values: 0.01 min |
batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
currency_code
string
|
Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
funding_source_token
string
|
ACH funding source token for the external account. Allowable Values: 36 char max |
last_modified_time
datetime
|
Date and time when the ACH transfer was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
memo
string
|
Additional text describing the ACH transfer. Allowable Values: 99 char max |
return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
standard_entry_class_code
string
|
Three-letter code identifying the type of entry.
Allowable Values:
|
statement_descriptor
string
|
Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
status
string
|
New state of the ACH transfer. Allowable Values:
|
token
string
|
Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
transfer_speed
string
|
Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values:
|
transitions
array of objects
|
Array of ACH transfer transition objects. Allowable Values: Valid array of one or more |
transitions[].bank_transfer_token
string
|
Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
transitions[].batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
transitions[].channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
transitions[].created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
transitions[].last_modified_time
datetime
|
Date and time when the ACH transfer was last modified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
transitions[].program_reserve_token
string
|
Not currently used. Allowable Values: 36 char max |
transitions[].reason
string
|
Explanation of why the transition is being made, for example "Created by POST call on API". Returned if this information was supplied when the transition was originally created. Allowable Values: 255 char max |
transitions[].return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
transitions[].return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
transitions[].status
string
|
New state of the ACH transfer. Allowable Values:
|
transitions[].token
string
|
Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
transitions[].transaction_jit_token
string
|
Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
transitions[].transaction_token
string
|
Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
type
string
|
Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values:
|
Create ACH transfer transition
Copy section link
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.
Request body
Copy section link
Create bank transfer transition request model
| Fields | Description |
|---|---|
bank_transfer_token
string
|
Token of the ACH transfer you want to transition. Allowable Values: 36 char max Existing ACH transfer token |
batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
program_reserve_token
string
|
Not currently used. Allowable Values: 36 char max Existing program reserve token |
reason
string
|
Description of why the ACH transfer status was updated. Allowable Values: 255 char max |
return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
NoteIf the transition is to theRETURNED state, a return_code should be supplied to indicate why the transaction is RETURNED.
|
status
string
|
New state of the ACH transfer. NOTE: In production environments, the only value to which you are allowed to transition an ACH transfer is Allowable Values:
|
token
string
|
Unique identifier of the bank transfer transition request. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
bank_transfer_token
string
|
Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the ACH transfer was last modified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
program_reserve_token
string
|
Not currently used. Allowable Values: 36 char max |
reason
string
|
Explanation of why the transition is being made, for example "Created by POST call on API". Returned if this information was supplied when the transition was originally created. Allowable Values: 255 char max |
return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
status
string
|
New state of the ACH transfer. Allowable Values:
|
token
string
|
Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
transaction_jit_token
string
|
Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
transaction_token
string
|
Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
List ACH transfer transitions
Copy section link
Action: GET
Endpoint: /banktransfers/ach/transitions
Retrieve a list of all ACH transfer transitions for a given ACH transfer.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of bank transfer transitions to retrieve. Allowable Values: 50 max 1-10 |
token
string
|
Unique identifier of the bank transfer transition. Allowable Values: Existing bank transfer transition token |
bank_transfer_token
string
|
Unique identifier of the bank transfer. Allowable Values: Existing bank transfer token |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
sort_by
string
|
Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values:
Default value: |
statuses
string
|
Comma-delimited list of bank transfer states to display. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
Array of ACH transfer transition objects. This field is returned if there are resources in your returned array. Allowable Values: A valid array of one or more ACH transfer transition objects |
data[].bank_transfer_token
string
|
Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
data[].batch_number
string
|
Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
data[].channel
string
|
Mechanism by which the transaction was initiated. Allowable Values:
|
data[].created_time
datetime
|
Date and time when the ACH transfer was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].last_modified_time
datetime
|
Date and time when the ACH transfer was last modified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].program_reserve_token
string
|
Not currently used. Allowable Values: 36 char max |
data[].reason
string
|
Explanation of why the transition is being made, for example "Created by POST call on API". Returned if this information was supplied when the transition was originally created. Allowable Values: 255 char max |
data[].return_code
string
|
Standardized ACH return code for a returned transaction, generally sent by the RDFI. Transactions can be returned for any of the reasons listed in the NACHA ACH return codes table of the ACH Origination Guide. Allowable Values:
|
data[].return_reason
string
|
Human-readable description correlating to the Allowable Values: 255 char max |
data[].status
string
|
New state of the ACH transfer. Allowable Values:
|
data[].token
string
|
Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
data[].transaction_jit_token
string
|
Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
data[].transaction_token
string
|
Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
end_index
integer
|
Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |