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 completed status.

Testing outbound payments can be achieved simply by using the standard payment origination API endpoint. The sandbox environment will automatically take the payment through the various statuses until it is completed. 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.

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 "TEST_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": "TEST_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 "TEST_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": "TEST_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 completed status, 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 was 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 completed 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 completed status. 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:

  • You originate an IAT for a receiver and our AML team needs additional information to validate the identity of that receiver.
  • You are unable to provide the required information to our AML team, so the payment is rejected in COS.

When a payment is manually rejected by someone in CRB, it is not accompanied by any standardized return code. The rejection scenarios that are accompanied by a code are only those related to items such as model validation failed Core postings.


Did this page help you?