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