Simulations

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 only simulate a return or NOC for a payment once it has updated to a status of Complete.

Testing outbound payments can be achieved simply by using the payment origination API endpoint. The sandbox environment will automatically take the payment through the various statuses until it is Complete. Typically this process will take 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 will take a few minutes before they show up as new payment records.

Inbound Originations

Inbound originations are payments that are originated at another financial institution and sent to your COS account.
These payments can have a transactionType of either Push (funds are being sent to your COS account) or Pull (funds are being taken from your COS 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.

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 would be the account in COS that is receiving the payment. Please see the Originating ACH Payments tutorial for additional information.

Returns

ACH returns can be simulated manually using the simulation endpoint, which can be found at this page. You'll need to 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.

POST /v1/payments/simulated-inbound-returns
{
  "returnCode": "R01",
  "previousPaymentId": "00000000-0000-0000-0000-000000000000"
}

Alternatively, returns 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 "RETURN_RXX", where XX is the return 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": "RETURN_R01"
}

The example above illustrates an outbound pull payment where a insufficient funds return (R01) will be automatically generated by COS after the outbound payment is complete.

POST /v1/payments/simulated-inbound-corrections
{
  "changeCode": "string",
  "correctedData": "string",
  "previousPaymentId": "00000000-0000-0000-0000-000000000000"
}

Corrections

Corrections (aka notifications of change) can be simulated manually using the simulation endpoint, which can be found at this page. 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.

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