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

# Overview

By default, all ACHs created in the sandbox environment are moved through the normal [ACH workflow](/reference/ach), eventually ending up with the status, `sent`. This accelerated processing happens at the top of every hour.

ACH simulations allow developers to manually trigger an ACH into various states that may arise in the course of production money movement. Developers can better understand the flow of funds by manually updating an ACH's status to `sent` or `returned` at an accelerated timeline, as defined in the "Simulation Types" table below. The corresponding impact to an account's balance, transaction(s), and [hold(s) (if applicable)](/reference/ach) can also be observed by calling the various respective endpoints.

Note that when using ACH simulations in Sandbox, the `service` field on the ACH object will be ignored and will not impact the simulation.

The three ACH simulation types are listed below.

<Warning>
  ACH Simulations are representative of ACH behavior on Treasury Prime ledger accounts. They may not exactly reflect on-core activity at every bank.
</Warning>

## ACH Simulation Types

| Simulation type          | Explanation                                                                                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ach.processing\_sent     | Simulate an ACH being sent by validating, processing and sending the ACH immediately. If an ACH fails validation or processing, the ACH is instead updated to an error status.                                                   |
| ach.processing\_returned | Simulate an ACH being returned by validating, processing, sending, and then returning the ACH immediately. Similarly to processing\_sent, any validation or processing failure will cause the ACH status to be updated to error. |
| ach.incoming\_ach        | Simulate an incoming credit or debit (externally originated) ACH.                                                                                                                                                                |

## Preparing for an ACH Simulation

To simulate a sent or returned ACH, an ACH object must be first be created via a `POST` request to the `/ach` endpoint with the following parameters included in the `userdata` field:

| Parameter             | Type    | Required? | Description                                                                                                                                                          |
| --------------------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manual                | boolean | Required  | `true` should be provided to indicate that this is a simulation request. This field prevents the ACH from automatically being processed at the top of the next hour. |
| scheduled\_settlement | integer |           | Only applicable to `debit` ACHs. The number of minutes to wait after the simulation is submitted to capture the ACH request. Defaults to `15` minutes if unset.      |

##### Example Request

<CodeGroup>
  ```bash bash theme={null}
  $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/ach \
      -H 'Content-Type: application/json' \
      -d '{
              "account_id": "acct_1234567890",
              "amount": "100.00",
              "counterparty_id": "cp_0987654321",
              "direction": "debit",
              "sec_code": "ccd",
              "userdata": {
                  "manual": true,
                  "scheduled_settlement": 0
              }
          }'
  ```
</CodeGroup>

## Create a Sent or Returned ACH Simulation

Initiate either an `ach.processing_sent` or an `ach.processing_returned` simulation.

<CodeGroup>
  ```bash bash theme={null}
  POST https://api.sandbox.treasuryprime.com/simulation
  ```
</CodeGroup>

### Sent or Returned ACH Simulation Request Body

| Parameter  | Type   | Required? | Description                       |
| ---------- | ------ | --------- | --------------------------------- |
| type       | string | Required  | The ACH simulation type.          |
| simulation | object | Required  | The simulation request subobject. |

#### Simulation Sub-Object

| Parameter | Type   | Required? | Description                                                    |
| --------- | ------ | --------- | -------------------------------------------------------------- |
| ach\_id   | string | Required  | ID of the ACH to use as the source for simulated transactions. |

##### Example Request

<CodeGroup>
  ```bash bash theme={null}
  $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/simulation \
      -H 'Content-Type: application/json' \
      -d '{
             "type": "ach.processing_sent",
             "simulation": {
                 "ach_id": "ach_123456"
             }
          }'
  ```
</CodeGroup>

##### Success Response

There will be no response body. The response code will be a `202 - accepted`.

##### Error Response

<CodeGroup>
  ```bash bash theme={null}
  {
    "error": "Invalid simulation request or simulation not implemented"
  }
  ```
</CodeGroup>

## Example: How to Simulate a Sent ACH

A common flow for an ACH simulation is creating an ACH, and then calling the simulation endpoint with the `id` of the ACH. See [ACH](/reference/ach) for example ACH requests. The following calls outline simulating an ACH sent simulation with a debit ACH.

##### Create ACH Request

<CodeGroup>
  ```bash bash theme={null}
  $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/ach \
      -H 'Content-Type: application/json' \
      -d '{
              "account_id": "acct_1234567890",
              "amount": "100.00",
              "counterparty_id": "cp_0987654321",
              "direction": "debit",
              "sec_code": "ccd",
              "userdata": {
                  "manual": true,
                  "scheduled_settlement": 0
              }
          }'
  ```
</CodeGroup>

##### Simulation Request

<CodeGroup>
  ```bash bash theme={null}
  $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/simulation \
      -H 'Content-Type: application/json' \
      -d '{
              "type": "ach.processing_sent",
              "simulation": {
                  "ach_id": "ach_104"
              }
          }'
  ```
</CodeGroup>

##### Simulation Response

No response body is returned. A `202` HTTP status indicates a successful simulation.

### Verifying a Successful Simulation

To ensure that the simulation was run successfully, call the `GET /ach/:id` endpoint to confirm that the status of the ACH has been updated to `sent` or `returned`. The funds should have been moved to/from an account and a corresponding transaction should appear.

## Create an Incoming ACH Simulation

Initiate an `ach.incoming_ach` simulation. Simulates an ACH that was originated externally from a different bank by creating a transaction on an account.

<CodeGroup>
  ```bash bash theme={null}
  POST https://api.sandbox.treasuryprime.com/simulation
  ```
</CodeGroup>

### Simulation Request Body

| Parameter            | Type   | Required? | Description                                                                                     |
| -------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------- |
| amount               | string | Required  | Amount of money in dollars to transfer, as a string with two-decimal precision.                 |
| account\_type        | string | Required  | The type of the account to send money to, as a string. Should be either `checking` or `savings` |
| direction            | string | Required  | Either `credit` or `debit`.                                                                     |
| sec\_code            | string | Required  | One of `ccd`, `cie`, `ppd`, `tel`, or `web`.                                                    |
| account\_number      | string | Required  | Bank account number for ACH use (maximum of 17 characters).                                     |
| company\_name        | string |           | The name of the company that originated this ACH.                                               |
| company\_description | string |           | Description of the company that originated this ACH.                                            |
| company\_id          | string |           | 10 digit unique identifier used to identify the originator collecting payments for a debit ACH. |

##### Example Request

The following call outlines simulating an incoming credit ACH.

<CodeGroup>
  ```bash bash theme={null}
  $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/simulation \
      -H 'Content-Type: application/json' \
      -d '{
              "type": "ach.incoming_ach",
              "simulation": {
                  "account_number": "123456789",
                  "account_type": "checking",
                  "amount": "100.00",
                  "direction": "credit",
                  "sec_code": "ccd",
                  "company_name": "Prime of Treasury Inc.",
                  "company_desc": "To infinity, and beyond!",
                  "company_id": "9876543210"
              }
          }'
  ```
</CodeGroup>

##### Success Response

There will be no response body. The response code will be a `202 - Accepted`.

##### Error Response

<CodeGroup>
  ```bash bash theme={null}
  {
    "error": "Invalid simulation request or simulation not implemented"
  }
  ```
</CodeGroup>