How to simulate ACH inbound payments

Simulations allow testing certain inbound payment flows in our sandbox environment. They can either be triggered 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 purpose field.

You can 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.

Inbound Originations

Inbound originations are payments that are originated at another financial institution and sent to your CR account.

These payments can have a transactionType of either Push (funds are being sent to your CR account) or Pull (funds are being taken from your CR account).

To simulate an inbound origination, you would manually trigger it using the simulated inbound originations endpoint. A sample of this request is displayed below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /v1/payments/simulated-inbound-originations
{
  "originatorRoutingNumber": "021000021",
  "originatorName": "Bob Smith",
  "originatorIdentification": "99999999",
  "receiverAccountNumber": "1234567890",
  "receiverAccountType": "Checking",
  "receiverName": "John Smith",
  "receiverIdentification": "INV123",
  "secCode": "PPD",
  "description": "Testing",
  "transactionType": "Push",
  "amount": 1000,
  "serviceType": "SameDay",  
}

The receiverAccountNumber is the number of the CR account receiving the payment. See How to originate an ACH payment for additional information.

Returns

You can simulate ACH returns manually using the simulation endpoint POST /v1/payments/simulated-inbound-returns. Populate the desired return code along with the ID of the outbound payment that you're trying to simulate a return for. A sample of this request is displayed below.

1
2
3
4
5
POST /v1/payments/simulated-inbound-returns
{
  "returnCode": "R01",
  "previousPaymentId": "00000000-0000-0000-0000-000000000000"
}

Alternatively, simulate a return automatically when originating an outbound payment. To do this, you'll need to use the purpose field of the payment request. Populate the purpose field with RETURN_RXX, where XX is the return code you wish to test. A sample of this request is displayed below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
POST /v1/payments
{
  "accountNumber": "2342123458",
  "receiver": {
    "routingNumber": "021200339",
    "accountNumber": "654321987",
    "accountType": "Checking",
    "name": "Glenn Quagmire",
    "identification": "XYZ123"
  },
  "secCode": "PPD",
  "description": "MembFee",
  "transactionType": "Pull",
  "amount": 4999,
  "serviceType": "Standard",
  "purpose": "RETURN_R01"
}

1
2
3
4
5
6
POST /v1/payments/simulated-inbound-corrections
{
  "changeCode": "string",
  "correctedData": "string",
  "previousPaymentId": "00000000-0000-0000-0000-000000000000"
}

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

Corrections

Corrections (notifications of change) can be simulated manually using the simulation endpoint. You'll need to populate the desired correction code along with the ID of the outbound payment that you're truing to simulate a correction for. A sample of this request is displayed below.

1
2
3
4
5
6
POST /v1/payments/simulated-inbound-corrections
{
  "changeCode": "C01",
  "correctedData": "12345",
  "previousPaymentId": "00000000-0000-0000-0000-000000000000"
}

Alternatively, corrections can be simulated automatically when originating an outbound payment. To do this, you'll need to use the purpose field of the payment request. Populate the purpose field with "NOC_CXX", where XX is the correction code you wish to test. A sample of this request is displayed below.

POST /v1/payments
{
  "accountNumber": "2342123458",
  "receiver": {
    "routingNumber": "021200339",
    "accountNumber": "654321987",
    "accountType": "Checking",
    "name": "Glenn Quagmire",
    "identification": "XYZ123"
  },
  "secCode": "PPD",
  "description": "MembFee",
  "transactionType": "Pull",
  "amount": 4999,
  "serviceType": "Standard"
  },
  "purpose": "NOC_C01"
}

The example above illustrates an outbound pull payment where an incorrect DFI account number correction (C01) will be automatically generated by the CR system after the outbound payment is complete.

Additional Information

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 CR 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 CR account had insufficient funds then you would see NSF as the PostingCode within the payment details..