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.
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.
/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.
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.
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
Action:POSTEndpoint:
/banktransfers/ach
Create an ACH transfer that pushes funds to an external account or pulls funds into your program funding account.
Request body
Create bank transfer request model| Fields | Description |
|---|---|
| amount decimal Required | Amount to push or pull. Allowable Values: 0.01 min |
| currency_code string Optional | Currency of the push or pull. Allowable Values: Valid alpha-3 ISO 4217 currency code Default value: USD |
| funding_source_token string Required | ACH funding source token for the external account. Allowable Values: 36 char max Existing ACH funding source token. |
| memo string Optional | Additional text describing the ACH transfer. Allowable Values: 255 char max |
| standard_entry_class_code string Optional | Three-letter code identifying the type of entry. - WEB — An internet-initiated entry - PPD — Prearranged Payment and Deposit - CCD — Corporate Credit or Debit Entry Allowable Values: WEB, PPD, CCD |
| statement_descriptor string Optional | Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
| token string Optional | Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
| transfer_speed string Optional | Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values: STANDARD, SAME_DAY |
| type string Optional | Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values: PUSH, PULL |
Sample request body
JSON
{
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PUSH",
"amount": 10.49,
"transfer_speed": "STANDARD",
"statement_descriptor": "ACHTRNSFR",
"standard_entry_class_code": "WEB",
"currency_code": "USD",
"memo": "Bank transfer"
}
Response body
| Fields | Description |
|---|---|
| amount decimal Returned | Amount to push or pull. Allowable Values: 0.01 min |
| batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| currency_code string Conditionally returned | Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
| funding_source_token string Returned | ACH funding source token for the external account. Allowable Values: 36 char max |
| last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| memo string Conditionally returned | Additional text describing the ACH transfer. Allowable Values: 99 char max |
| return_code string Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| standard_entry_class_code string Conditionally returned | Three-letter code identifying the type of entry. - WEB — An internet-initiated entry - PPD — Prearranged Payment and Deposit - CCD — Corporate Credit or Debit Entry Allowable Values: WEB, PPD, CCD |
| statement_descriptor string Conditionally returned | Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
| status string Conditionally returned | New state of the ACH transfer. Allowable Values: INITIATED, PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, ERROR, CANCELLED |
| token string Conditionally returned | Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
| transfer_speed string Conditionally returned | Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values: STANDARD, SAME_DAY |
| transitions array of objects Conditionally returned | Array of ACH transfer transition objects. Allowable Values: Valid array of one or more transitions objects |
| transitions[].bank_transfer_token string Returned | Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
| transitions[].batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| transitions[].channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| transitions[].created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| transitions[].last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| transitions[].program_reserve_token string Conditionally returned | Not currently used. Allowable Values: 36 char max |
| transitions[].reason string Conditionally returned | 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 Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| transitions[].return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| transitions[].status string Returned | New state of the ACH transfer. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| transitions[].token string Conditionally returned | Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
| transitions[].transaction_jit_token string Conditionally returned | Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
| transitions[].transaction_token string Conditionally returned | Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
| type string Conditionally returned | Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values: PUSH, PULL |
Sample response body
JSON
{
"token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"amount": 10.49,
"memo": "Bank transfer",
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"statement_descriptor": "ACHTRNSFR",
"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": "2024-03-20T18:32:32Z",
"last_modified_time": "2024-03-20T18:32:32Z"
}
],
"created_time": "2024-03-20T18:32:32Z",
"last_modified_time": "2024-03-20T18:32:32Z"
}
List ACH transfers
Action:GETEndpoint:
/banktransfers/ach
Retrieve a list of all ACH transfers.
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of resources to retrieve. Allowable Values: 1-10 |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| user_token string Optional | Unique identifier of the user resource. Allowable Values: Existing user token |
| business_token string Optional | Unique identifier of the business resource. Allowable Values: Existing business token |
| funding_source_token string Optional | Unique identifier of the funding source. Allowable Values: Existing funding_source token |
| statuses string Optional | Comma-delimited list of bank transfer statuses. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| sort_by string Optional | 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: createdTime, lastModifiedTime, or any field in the resource modelDefault value: -lastModifiedTime |
| expand string Optional | Returns the full funding source object when fundingsource is passed. Otherwise, returns the funding source token.Allowable Values: fundingsource or blank |
| funding_source_type string Optional | Funding source type to filter. Allowable Values: USER, PROGRAM |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
| data array of objects Conditionally returned | 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 Returned | Amount to push or pull. Allowable Values: 0.01 min |
| data[].batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| data[].created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].currency_code string Conditionally returned | Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
| data[].funding_source_token string Returned | ACH funding source token for the external account. Allowable Values: 36 char max |
| data[].last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].memo string Conditionally returned | Additional text describing the ACH transfer. Allowable Values: 99 char max |
| data[].return_code string Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| data[].return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| data[].standard_entry_class_code string Conditionally returned | Three-letter code identifying the type of entry. - WEB — An internet-initiated entry - PPD — Prearranged Payment and Deposit - CCD — Corporate Credit or Debit Entry Allowable Values: WEB, PPD, CCD |
| data[].statement_descriptor string Conditionally returned | Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
| data[].status string Conditionally returned | New state of the ACH transfer. Allowable Values: INITIATED, PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, ERROR, CANCELLED |
| data[].token string Conditionally returned | Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
| data[].transfer_speed string Conditionally returned | Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values: STANDARD, SAME_DAY |
| data[].transitions array of objects Conditionally returned | Array of ACH transfer transition objects. Allowable Values: Valid array of one or more transitions objects |
| data[].transitions[].bank_transfer_token string Returned | Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
| data[].transitions[].batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| data[].transitions[].channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| data[].transitions[].created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].transitions[].last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].transitions[].program_reserve_token string Conditionally returned | Not currently used. Allowable Values: 36 char max |
| data[].transitions[].reason string Conditionally returned | 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 Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| data[].transitions[].return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| data[].transitions[].status string Returned | New state of the ACH transfer. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| data[].transitions[].token string Conditionally returned | Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
| data[].transitions[].transaction_jit_token string Conditionally returned | Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
| data[].transitions[].transaction_token string Conditionally returned | Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
| data[].type string Conditionally returned | Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values: PUSH, PULL |
| end_index integer Conditionally returned | 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 Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | 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 |
Sample response body
JSON
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"amount": 10.49,
"memo": "Bank transfer",
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"statement_descriptor": "ACHTRNSFR",
"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": "2024-03-20T18:32:32Z",
"last_modified_time": "2024-03-20T18:33:32Z"
}
],
"created_time": "2024-03-20T18:32:32Z",
"last_modified_time": "2024-03-20T18:33:32Z"
},
{
"token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"amount": 100.11,
"funding_source_token": "bbaefe8f-f5d0-43f6-8576-16f562d23f3f",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"statement_descriptor": "ACHTRNSFR",
"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": "2024-03-22T18:01:00Z",
"last_modified_time": "2024-03-22T18:02:00Z"
},
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "Created by `POST` call on API",
"channel": "API",
"created_time": "2024-03-22T18:01:17Z",
"last_modified_time": "2024-03-22T18:01:27Z"
}
]
}
],
"created_time": "2024-03-22T18:01:00Z",
"last_modified_time": "2024-03-22T18:02:17Z"
}
Perform faster funds ACH transfer
Action:POSTEndpoint:
/banktransfers/ach/earlyfunds
Use this endpoint to post funds from an existing bank transfer more quickly to the cardholder’s account.
Request body
| Fields | Description |
|---|---|
| bank_transfer_token string Required | Unique identifier of the ACH transfer whose funds you want to post more quickly to the cardholder’s account. Allowable Values: 36 char max Existing ACH transfer token |
Sample request body
JSON
{
"bank_transfer_token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788"
}
Response body
| Fields | Description |
|---|---|
| amount decimal Returned | Amount to push or pull. Allowable Values: 0.01 min |
| batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| currency_code string Conditionally returned | Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
| funding_source_token string Returned | ACH funding source token for the external account. Allowable Values: 36 char max |
| last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| memo string Conditionally returned | Additional text describing the ACH transfer. Allowable Values: 99 char max |
| return_code string Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| standard_entry_class_code string Conditionally returned | Three-letter code identifying the type of entry. - WEB — An internet-initiated entry - PPD — Prearranged Payment and Deposit - CCD — Corporate Credit or Debit Entry Allowable Values: WEB, PPD, CCD |
| statement_descriptor string Conditionally returned | Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
| status string Conditionally returned | New state of the ACH transfer. Allowable Values: INITIATED, PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, ERROR, CANCELLED |
| token string Conditionally returned | Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
| transfer_speed string Conditionally returned | Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values: STANDARD, SAME_DAY |
| transitions array of objects Conditionally returned | Array of ACH transfer transition objects. Allowable Values: Valid array of one or more transitions objects |
| transitions[].bank_transfer_token string Returned | Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
| transitions[].batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| transitions[].channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| transitions[].created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| transitions[].last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| transitions[].program_reserve_token string Conditionally returned | Not currently used. Allowable Values: 36 char max |
| transitions[].reason string Conditionally returned | 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 Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| transitions[].return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| transitions[].status string Returned | New state of the ACH transfer. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| transitions[].token string Conditionally returned | Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
| transitions[].transaction_jit_token string Conditionally returned | Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
| transitions[].transaction_token string Conditionally returned | Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
| type string Conditionally returned | Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values: PUSH, PULL |
Sample response body
JSON
{
"token": "cf3b49d8-bd68-4fb1-8da5-c170cff3d788",
"amount": 10.49,
"memo": "Bank transfer",
"funding_source_token": "d331b4b2-cef5-49a3-9c41-75d8f4e15cfz",
"type": "PULL",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"statement_descriptor": "ACHTRNSFR",
"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": "2024-03-20T18:32:32Z",
"last_modified_time": "2024-03-20T18:32:32Z"
}
],
"created_time": "2024-03-20T18:32:32Z",
"last_modified_time": "2024-03-20T18:32:32Z"
}
Retrieve ACH transfer
Action:GETEndpoint:
/banktransfers/ach/{token}
Retrieve a specific ACH transfer.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the bank transfer. Allowable Values: Existing bank transfer token |
Response body
| Fields | Description |
|---|---|
| amount decimal Returned | Amount to push or pull. Allowable Values: 0.01 min |
| batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| currency_code string Conditionally returned | Valid alpha-3 ISO 4217 currency code Allowable Values: Valid alpha-3 ISO 4217 currency code |
| funding_source_token string Returned | ACH funding source token for the external account. Allowable Values: 36 char max |
| last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| memo string Conditionally returned | Additional text describing the ACH transfer. Allowable Values: 99 char max |
| return_code string Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| standard_entry_class_code string Conditionally returned | Three-letter code identifying the type of entry. - WEB — An internet-initiated entry - PPD — Prearranged Payment and Deposit - CCD — Corporate Credit or Debit Entry Allowable Values: WEB, PPD, CCD |
| statement_descriptor string Conditionally returned | Description of the transaction, as it will appear on the receiver’s bank statement. Allowable Values: 10 char max |
| status string Conditionally returned | New state of the ACH transfer. Allowable Values: INITIATED, PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, ERROR, CANCELLED |
| token string Conditionally returned | Unique identifier of the ACH transfer to retrieve. Allowable Values: 36 char max |
| transfer_speed string Conditionally returned | Specifies how quickly to initiate the ACH transfer. NOTE: Same-day transfers are limited to a maximum amount of $100,000. Allowable Values: STANDARD, SAME_DAY |
| transitions array of objects Conditionally returned | Array of ACH transfer transition objects. Allowable Values: Valid array of one or more transitions objects |
| transitions[].bank_transfer_token string Returned | Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
| transitions[].batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| transitions[].channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| transitions[].created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| transitions[].last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| transitions[].program_reserve_token string Conditionally returned | Not currently used. Allowable Values: 36 char max |
| transitions[].reason string Conditionally returned | 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 Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| transitions[].return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| transitions[].status string Returned | New state of the ACH transfer. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| transitions[].token string Conditionally returned | Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
| transitions[].transaction_jit_token string Conditionally returned | Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
| transitions[].transaction_token string Conditionally returned | Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
| type string Conditionally returned | Specifies whether the ACH transfer is a push (credit) or pull (debit). Allowable Values: PUSH, PULL |
Sample response body
JSON
{
"token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"amount": 100.11,
"funding_source_token": "bbaefe8f-f5d0-43f6-8576-16f562d23f3f",
"type": "PUSH",
"currency_code": "USD",
"transfer_speed": "STANDARD",
"statement_descriptor": "ACHTRNSFR",
"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": "2024-03-22T18:01:00Z",
"last_modified_time": "2024-03-22T18:01:00Z"
},
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "Created by `POST` call on API",
"channel": "API",
"created_time": "2024-03-22T18:01:17Z",
"last_modified_time": "2024-03-22T18:01:17Z"
}
],
"created_time": "2024-03-22T18:01:00Z",
"last_modified_time": "2024-03-22T18:01:17Z"
}
Create ACH transfer transition
Action:POSTEndpoint:
/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.
You can create ACH transfer transitions in the sandbox environment. However, Marqeta transitions ACH transfers through their lifecycle in the production environment.
Request body
Create bank transfer transition request model| Fields | Description |
|---|---|
| bank_transfer_token string Required | Token of the ACH transfer you want to transition. Allowable Values: 36 char max Existing ACH transfer token |
| batch_number string Optional | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| channel string Required | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| program_reserve_token string Optional | Not currently used. Allowable Values: 36 char max Existing program reserve token |
| reason string Optional | Description of why the ACH transfer status was updated. Allowable Values: 255 char max |
| return_code string Optional | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85NOTE|OPEN|| CALLOUTTITLE:Note|TITLEBREAK|If the transition is to the RETURNED state, a return_code should be supplied to indicate why the transaction is RETURNED . NOTE|CLOSE |
| status string Required | New state of the ACH transfer. NOTE: In production environments, the only value to which you are allowed to transition an ACH transfer is CANCELLED.Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| token string Optional | Unique identifier of the bank transfer transition request. Allowable Values: 36 char max |
Sample request body
JSON
{
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "CANCELLED",
"channel": "API"
}
Response body
| Fields | Description |
|---|---|
| bank_transfer_token string Returned | Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
| batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| program_reserve_token string Conditionally returned | Not currently used. Allowable Values: 36 char max |
| reason string Conditionally returned | 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 Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| status string Returned | New state of the ACH transfer. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| token string Conditionally returned | Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
| transaction_jit_token string Conditionally returned | Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
| transaction_token string Conditionally returned | Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
Sample response body
JSON
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "CANCELLED",
"channel": "API",
"created_time": "2024-03-22T18:01:17Z",
"last_modified_time": "2024-03-22T18:01:17Z"
}
List ACH transfer transitions
Action:GETEndpoint:
/banktransfers/ach/transitions
Retrieve a list of all ACH transfer transitions for a given ACH transfer.
URL query parameters
| Fields | Description |
|---|---|
| count integer Optional | Number of bank transfer transitions to retrieve. Allowable Values: 50 max 1-10 |
| token string Optional | Unique identifier of the bank transfer transition. Allowable Values: Existing bank transfer transition token |
| bank_transfer_token string Optional | Unique identifier of the bank transfer. Allowable Values: Existing bank transfer token |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| sort_by string Optional | 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: createdTime, lastModifiedTime, or any field in the resource modelDefault value: -lastModifiedTime |
| statuses string Optional | Comma-delimited list of bank transfer states to display. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
| data array of objects Conditionally returned | 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 Returned | Unique identifier of the ACH transfer being transitioned. Allowable Values: 36 char max |
| data[].batch_number string Conditionally returned | Field required in older versions of the API, but no longer used. Allowable Values: Any integer |
| data[].channel string Returned | Mechanism by which the transaction was initiated. Allowable Values: API, SYSTEM |
| data[].created_time datetime Conditionally returned | Date and time when the ACH transfer was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].last_modified_time datetime Conditionally returned | Date and time when the ACH transfer was last modified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].program_reserve_token string Conditionally returned | Not currently used. Allowable Values: 36 char max |
| data[].reason string Conditionally returned | 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 Conditionally returned | 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: R01, R02, R03, R04, R05, R06, R07, R08, R09, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31, R32, R33, R34, R35, R37, R38, R39, R40, R41, R42, R43, R44, R45, R46, R47, R50, R51, R52, R53, R61, R67, R68, R69, R70, R71, R72, R73, R74, R75, R76, R80, R81, R82, R83, R84, R85 |
| data[].return_reason string Conditionally returned | Human-readable description correlating to the return_code, such as Insufficient funds, if a return code is present in the response.Allowable Values: 255 char max |
| data[].status string Returned | New state of the ACH transfer. Allowable Values: PENDING, PROCESSING, SUBMITTED, RETURNED, COMPLETED, CANCELLED |
| data[].token string Conditionally returned | Unique identifier of the bank transfer transition. Allowable Values: 36 char max |
| data[].transaction_jit_token string Conditionally returned | Transaction token for JIT-related ledger entries for the ACH transfer. Allowable Values: Existing JIT Funding transaction token |
| data[].transaction_token string Conditionally returned | Transaction token for non-JIT-related ledger entries for the ACH transfer. Allowable Values: Existing transaction token |
| end_index integer Conditionally returned | 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 Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | 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 |
Sample response body
JSON
{
"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": "2024-03-22T18:01:00Z",
"last_modified_time": "2024-03-22T18:01:00Z"
},
{
"token": "55f5b1ac-39f6-484d-8284-116046a2efaa",
"bank_transfer_token": "f8b8245f-fc36-49f3-9f9f-f63b159501b7",
"status": "PROCESSING",
"reason": "Created by `POST` call on API",
"channel": "API",
"created_time": "2024-03-22T18:01:17Z",
"last_modified_time": "2024-03-22T18:01:17Z"
}
]
}