Simulate inbound ACH
What you will learn
✅ How to simulate in sandbox for ACH:
- Inbound originations
- Returns
- Corrections (NOC )
If you are new to APIs and how the work we recommend you visit API basics.
The tutorial uses these API endpoints:
API | Description |
|---|---|
POST /v1/payments/simulated-inbound-originations | Simulates sending funds sent via ACH to a Cross River account from another bank. This endpoint can also be used to fund an account in sandbox. |
POST /v1/payments/simulated-inbound-returns | Simulates return of a payment from outside Cross River |
POST /v1/payments/simulated-inbound-corrections | Simulates a notification of change (NOC) |
Before you begin
Make sure you have:
- API credentials for sandbox access
- Cross River account number
- For returns and corrections, payment IDs of completed payments
Simulate ACH actions
Simulations allow you to test certain inbound payment flows in our sandbox environment. You can trigger these flows explicitly using the API endpoints outlined below, or, in the case of returns and corrections, automatically once an outbound payment completes. Automatic simulations are triggered by convention using the payment purposefield.
IMPORTANT You can only simulate a return or NOC for a payment once it has updated to a status of Complete.
Test outbound payments using the payment origination API endpoint. The sandbox environment automatically takes the payment through the various statuses until it is Complete. Typically this process takes up to several minutes from start to finish.
Where's my simulated payment?
It is important to note that simulation requests are queued and processed asynchronously on a schedule. It typically takes a few minutes before they show up as new payment records.
To simulate an inbound ACH payment
Inbound originations are payments that originate at another financial institution and are sent to a Cross River account.
These payments can have a transactionType of either Push (funds are being sent to your Cross River account) or Pull (funds are being taken from your Cross River account).
To simulate an inbound origination, manually trigger it using the simulated inbound originations endpoint.
Call POST /v1/payments/simulated-inbound-originations.
Required fields:
Attribute | Description | Value for simulation |
|---|---|---|
originatorRoutingNumber | Routing number of a bank outside Cross River | 021000021 |
originatorName | Name of bank account holder | Tom Smith |
originatorIdentification | Identifier for the bank account | 99999999 |
receiverAccountNumber | Account number of the sandbox account to receive the funds | Your sandbox account |
receiverAccountType | Type of account receiving the funds. One of:
| The type of account your sandbox account is |
receiverName | Name on the account receiving the funds | The name on your sandbox account |
secCode | Standard Entry Class (SEC) code required by Nacha for every ACH transaction | For the simulation we recommend using PPD |
description | Description of the payment. Maximum 10 characters. | For the simulation we recommend writing Testing |
transactionType | Sending or requesting funds:
See Payment types. | Use Push if you are funding a sandbox account |
amount | Dollar amount of payment in positive integral cents. For example, $1.00 appears as 100. | |
serviceType | |
See Send an ACH for additional information.
curl --location 'https://sandbox.crbcos.com/ach/v1/payments/simulated-inbound-originations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"originatorRoutingNumber": "021000021",
"originatorName": "Tom Smith",
"originatorIdentification": "99999999",
"receiverAccountNumber": "2819503463",
"receiverAccountType": "Checking",
"receiverName": "Jerry Penn",
"receiverIdentification": "INV123",
"secCode": "PPD",
"description": "Testing",
"transactionType": "Push",
"amount": 1000,
"serviceType": "SameDay",
}'A successful API call returns a JSON response with the details of the payment.
{
"originatorRoutingNumber": "021000021",
"originatorName": "Tom Smith",
"originatorIdentification": "99999999",
"receiverAccountNumber": "2819503463",
"receiverAccountType": "Checking",
"receiverName": "Jerry Penn",
"receiverIdentification": "INV123",
"secCode": "PPD",
"description": "Testing",
"transactionType": "Push",
"amount": 1000,
"serviceType": "SameDay",
"settlementDays": 0
}To simulate an ACH return
You can simulate an ACH return with the simulation endpoint POST /v1/payments/simulated-inbound-returns or with the Send an ACH API.
To use the simulation endpoint:
Have ready the ID of the outbound payment you are simulating the return for (found in the response of the Send an ACH) and a return code.
Call POST /v1/payments/simulated-inbound-returns.
curl --location 'https://sandbox.crbcos.com/ach/v1/payments/simulated-inbound-returns' \
--data '{
"returnCode": "R02",
"previousPaymentId": "1b228f4c-26d4-4da0-b813-b34300e84b4e"
}'A successful API call returns a JSON response.
{
"returnCode": "R02",
"previousPaymentId": "1b228f4c-26d4-4da0-b813-b34300e84b4e"
}To simulate a return automatically using the Send an ACH API:
When you send the POST /v1/payments call, populate the purpose field (row 18 below) with TEST_RETURN_RXX, where XX is the return code you wish to test.
curl --location 'https://sandbox.crbcos.com/ach/v1/payments' \
--header 'Idempotency-key: c10314ee-e737-4681-8e8d-f9cf547c9967' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"accountNumber": "2203250853",
"receiver": {
"routingNumber": "021000021",
"accountNumber": "2151546989",
"accountType": "Checking",
"name": "Peter Griffin"
},
"secCode": "PPD",
"description": "math tutor",
"transactionType": "Push",
"amount": 25000,
"serviceType": "Standard",
"purpose": "TEST_RETURN_R01"
}Contested returns have to be anticipated or approved for acceptance. In that case, only the initial return event is listed as returned, and a subsequent webhook is applied. The dishonoring of the return relays the funds back to the returning source and no webhook launches for those or any other rejecting/dishonoring attempts.
Without your direct consent, no returns of any kind occur while outside of the 24-hour (Corporate return) or 60-day (Consumer return) time frame . Transactions received outside of both scenarios are subject to review and processing. For any claims issued to the Cross River ACH Operations team, a notice is provided to the Originating party for Proof of Authorization or any other corroborating documents that warrant the authorization of the debit entry. Your RM will also be advised of any matters for awareness.
To simulate a correction
You can simulate an ACH NOC correction with the simulation endpoint POST /v1/payments/simulated-inbound-corrections or with the Send an ACH API.
To use the simulation endpoint:
Have ready the ID of the outbound payment you are simulating the correction for (found in the response of the Send an ACH), the correction and the correction code.
Call POST /v1/payments/simulated-inbound-corrections.
curl --location 'https://sandbox.crbcos.com/ach/v1/payments/simulated-inbound-corrections' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"changeCode": "C04",
"correctedData": "Peter G Griffen",
"previousPaymentId": "04228e9c-361e-4005-b68f-b339008ae4dc"
}'A successful API call returns a JSON response.
{
"changeCode": "C04",
"correctedData": "Peter G Griffen",
"previousPaymentId": "04228e9c-361e-4005-b68f-b339008ae4dc"
}'To simulate a NOC correction automatically using the Send an ACH API:
When you send the POST /v1/payments call, populate the purpose field (row 18 below) with TEST_NOC_CXX, where XX is the correction code you wish to test.
Our example shows an outbound pull payment where an incorrect DFI account number correction (C01) will be automatically generated by the Cross River system after the outbound payment is complete.
curl --location 'https://sandbox.crbcos.com/ach/v1/payments' \
--header 'Idempotency-key: c10314ee-e737-4681-8e8d-f9cf547c9967' \
--header 'Content-Type: application/json' \
--data '{
"accountNumber": "2203250853",
"receiver": {
"routingNumber": "021000021",
"accountNumber": "2151546989",
"accountType": "Checking",
"name": "Peter Griffin"
},
"secCode": "PPD",
"description": "math tutor",
"transactionType": "Push",
"amount": 25000,
"serviceType": "Standard",
"purpose": "TEST_NOC_C01",
}'Simulations explained
Since returns and NOCs can only be simulated after an outbound payment reaches a status of Complete, the outbound payment's service type will affect the timing of your simulations. An outbound payment with a standard service type would only allow you to simulate a return the following day via the simulation endpoint. If the simulation was done using the purpose field of the outbound payment, then you'd automatically receive the simulated inbound payment two business days after the payment is completed. Some SEC codes will also encounter this timing scenario, such as IATs which are restricted to a standard service type.
This is generally why you would encounter any scenarios where you’ve originated a payment but the status hasn’t changed to Complete in over 24 business hours. If you originated any payments yesterday, you can use the simulation endpoints to simulate any return code you want.
Our ACH domain in Sandbox is configured to simulate the bank’s processes around ACH origination, which means that generally no human intervention is needed to action a payment in order for it to be processed and moved to a status of Complete. We do not mark any payments as paid; once you originate a payment, assuming all systemic validations pass then Sandbox will simulate the payment being sent to the Fed and also simulate receiving an acknowledgment file from the Fed.
When a payment request is submitted to COS, the bank can reject the payment for various reasons. For example, a payment which was on hold for compliance reasons was rejected because the partner was unable to provide additional payment-related information.
Payments which are manually rejected by someone in Cross River do not include any details for the rejection. Payments which are systemically rejected will contain the reason within the payment details. For example, if a payment was rejected because the originator Cross River account had insufficient funds then you would see NSF as the postingCode within the payment details.