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 thename
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.
- Client-initiated simulated failures only cover originated transactions, between
general
and eitherwire_external
,instant_payments_external
, andach_external
Synthetic Accounts. Incoming transactions initiated by Counterparties can be simulated by our Newline Specialists at the Client's request. - The Transfer will move through our status workflow in the following order:
queued
,pending
, thenfailed
. - An MQ message will also be sent each time the Transfer and Transaction statuses are updated.
- 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:
Note
The below flows detail how to trigger both Notifications of Change (i.e., warnings) and Returns (i.e., failures).
Notifications of Change
- Submit a Transfer but place the text "noc_code_co2" (not case sensitive) in the
addenda
field. - The Transaction, when queried, will have the following fields populated:
noc_code
as "CO2",noc_reason
as "Incorrect Transit Routing Number".
Returns
- Submit a Transfer, and based on the
source_synthetic_account_uid
anddestination_synthetic_account_uid
, it will either be an ACH credit (i.e., ODFI pull), ACH debit (i.e., ODFI push), or prenote. Our debit or credit term use is framed from the perspective of the source account. - Once that Transfer's
status
issettled
, 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 theach_return_code
as "R01" andach_return_reason
as "Insufficient Funds". - If the Transaction is an ACH Debit, the
ach_return
Transaction will have theach_return_code
as "R02" andach_return_reason
as "Account Closed". - If the Transaction is a Prenote, the
ach_return
Transaction will have theach_return_code
as "R03" andach_return_reason
as "No Account/Unable to Locate Account".
- If the Transaction is an ACH Credit, the
Updated about 1 month ago
Learn more about the types of Synthetic Accounts configured for Sandbox use!