Overview

By default, all ACHs created in the sandbox environment are moved through the normal ACH workflow, 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) 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.

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

ACH Simulation Types

Simulation type	Explanation
ach.processing_sent	Simulate an ACH being sent by validating, processing and sending the ACH immediately. See Simulation errors for how failures are reported.
ach.processing_returned	Simulate an ACH being returned by validating, processing, sending, and then returning the ACH. Credit ACHs are returned immediately. Debit ACHs move to `sent` and then to `returned` after the number of minutes in `userdata.scheduled_settlement` (default `15`). The returned ACH always has return code `R01` in its `error` field; you can’t choose a different return reason.
ach.incoming_ach	Simulate an incoming credit or debit (externally originated) ACH.

Simulation errors

If the simulation request fails validation, the API returns a 400 response with an error message and leaves the ACH unchanged. Validation fails when:

The ACH doesn’t exist.
The ACH’s status is sent, returned, or error.
userdata.manual on the ACH isn’t true.
userdata.scheduled_settlement on the ACH isn’t an integer greater than or equal to 0.

If the ACH passes validation but can’t be processed, the API returns a 500 response with an error message, and the ACH may be left in error status.

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

$ 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
            }
        }'

Create a Sent or Returned ACH Simulation

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

POST https://api.sandbox.treasuryprime.com/simulation

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

$ 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"
           }
        }'

Success Response

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

Error Response

{
  "error": "Invalid simulation request or simulation not implemented"
}

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 for example ACH requests. The following calls outline simulating an ACH sent simulation with a debit ACH.

Create ACH Request

$ 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
            }
        }'

Simulation Request

$ 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"
            }
        }'

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.

POST https://api.sandbox.treasuryprime.com/simulation

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_desc	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.

$ 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"
            }
        }'

Success Response

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

Error Response

{
  "error": "Invalid simulation request or simulation not implemented"
}

Introduction

Account

Account Opening

Cards

Payments

Testing

Utilities

ACH Simulation Types

Simulation errors

Preparing for an ACH Simulation

Example Request

Create a Sent or Returned ACH Simulation

Sent or Returned ACH Simulation Request Body

Simulation Sub-Object

Example Request

Success Response

Error Response

Example: How to Simulate a Sent ACH

Create ACH Request

Simulation Request

Simulation Response

Verifying a Successful Simulation

Create an Incoming ACH Simulation

Simulation Request Body

Example Request

Success Response

Error Response

​ACH Simulation Types

​Simulation errors

​Preparing for an ACH Simulation

Example Request

​Create a Sent or Returned ACH Simulation

​Sent or Returned ACH Simulation Request Body

​Simulation Sub-Object

Example Request

Success Response

Error Response

​Example: How to Simulate a Sent ACH

Create ACH Request

Simulation Request

Simulation Response

​Verifying a Successful Simulation

​Create an Incoming ACH Simulation

​Simulation Request Body

Example Request

Success Response

Error Response

ACH Simulation Types

Simulation errors

Preparing for an ACH Simulation

Create a Sent or Returned ACH Simulation

Sent or Returned ACH Simulation Request Body

Simulation Sub-Object

Example: How to Simulate a Sent ACH

Verifying a Successful Simulation

Create an Incoming ACH Simulation

Simulation Request Body