Testing Error Scenarios

Any testing environment would be incomplete without the ability to test failures or errors. The Newline Sandbox is designed to prepare our clients and their respective end-customers, for every scenario.

Below, you'll find sections detailing how to initiate failures for specific APIs and types of Transfers. For example, how to simulate an ACH credit origination failure vs. an outgoing Wire failure. For each failure below, you'll want to review the Sandbox section in our API Reference, as it details the fields mentioned.

Virtual Reference Numbers

For Virtual Reference Number testing, failure cases are designed to mock issues when trying to both create the VRN and when trying to register the VRN for Instant Payment use.

VRN Creation

To trigger a failed VRN creation, follow this flow:

• Submit a request to create a VRN but have the name field start with the text "fail".

VRN Registration

To trigger a failed VRN registration, follow this flow:

• Submit a request to create a VRN, set the synchronous_registration field to "false", and have the name field start with the text "instant payment fail".

Payments

For Payments testing, failure cases are designed to mock expected durations of the payment type in question. For example, Wire failures will take roughly 2 seconds.

Additionally, the following points will be true for any simulated payment failure.

1. Client-initiated simulated failures only cover originated transactions, between general and either wire_external, instant_payments_external, and ach_external Synthetic Accounts. Incoming transactions initiated by Counterparties can be simulated by our Newline Specialists at the Client's request.
2. The Transfer will move through our status workflow in the following order: queued, pending, then failed.
3. An MQ message will also be sent each time the Transfer and Transaction statuses are updated.
4. Once the Transfer is initiated and appropriately fails, you'll be able to query the corresponding transaction record per normal API interaction.

Wire

To trigger a failed Wire, follow this flow:

• Submit a Transfer, but place the text "fail" (not case sensitive) in the wire_instructions field.

Instant Payments

To trigger a failed Instant Payment, follow this flow:

• Submit a Transfer, but place the text "fail" (not case sensitive) in the memo field.

📘

Note

The Sandbox does not populate the failure code or failure reason for a simulated Instant Payment failure.

ACH

To trigger a failed or at-risk ACH entry, follow these flows:

Notifications of Change

• Submit a Transfer but place the text "noc code co2" (not case sensitive) in the addenda field.
• About 1 hour later, the same transaction will update with NOC information populated:
  • "noc_code" = "CO2"
  • "noc_reason" = "Incorrect Transit Routing Number"
• This will also create a message queue event with type notification_of_change.

Returns

• Submit a Transfer, and based on the source_synthetic_account_uid and destination_synthetic_account_uid, it will either be an ACH credit (i.e., ODFI pull), ACH debit (i.e., ODFI push). Our debit or credit term use is framed from the perspective of the source account.
• Once that Transfer's status is settled, then supply the resulting Transaction's uid to simulate an ACH return.
  • If the Transaction is an ACH Credit, the ach_return Transaction will have the ach_return_code as "R01" and ach_return_reason as "Insufficient Funds".
  • If the Transaction is an ACH Debit, the ach_return Transaction will have the ach_return_code as "R02" and ach_return_reason as "Account Closed".