> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create ACH transfer transition

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

POST/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:

![ACH transfer lifecycle](https://mintcdn.com/marqeta-b295cded/TxQgVKoSBbsxuEcD/images/docs/core-api/funding-via-ach/achtransfers1.svg?fit=max\&auto=format\&n=TxQgVKoSBbsxuEcD\&q=85\&s=11e6ea3965b0d1a82a17b95da7369934)

> [!NOTE]
>
> **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

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](https://www.marqeta.com/docs/developer-guides/ach-origination.md#_nacha_ach_return_codes) 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`  NOTE\|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 JSON lines wrap theme={null}
{
  "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](https://www.marqeta.com/docs/developer-guides/ach-origination.md#_nacha_ach_return_codes) 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 JSON lines wrap theme={null}
{
  "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"
}
```


## Related topics

- [Funding via ACH Overview](https://www.marqeta.com/docs/core-api/funding-via-ach.md)
- [Create ACH transfer](https://www.marqeta.com/docs/core-api/funding-via-ach/create-ach-transfer.md)
- [List ACH transfer transitions](https://www.marqeta.com/docs/core-api/funding-via-ach/list-transfer-transitions.md)
- [ACH Origination](https://www.marqeta.com/docs/developer-guides/ach-origination.md)
- [Retrieve ACH transfer](https://www.marqeta.com/docs/core-api/funding-via-ach/retrieve-ach-transfer.md)