Returns Guide

Welcome to the Returns Guide for Newline’s API Sandbox. This guide outlines the process of submitting returns, initiating reversals, handling errors, and understanding transaction statuses. Please refer to the published documentation links for complete technical details.

Overview of the Returns Endpoint

The Returns Endpoint allows you to initiate ACH and wire returns, as well as ACH reversals, within the Sandbox environment. It provides a structured workflow to ensure returns are processed efficiently and in accordance with Newline’s transaction protocols. The endpoint documentation is available here:

• Returns Endpoint Documentation
• API Error Codes

Transaction Types for Returns

Below are transaction types for returns initiated by a Client:

• initiated_ach_return: An ACH return initiated by a Client through the Returns endpoint. Identifies an ACH Return of a received ACH transaction.
• initiated_wire_return: A wire return initiated by a Client through the Returns endpoint. Identifies a return of a received wire transaction.
• initiated_ach_reversal: An ACH reversal initiated by a Client through the Returns endpoints. Identifies an ACH Reversal to reverse an initiated ACH transaction.

For complete details, visit the Transaction Statuses and Types Documentation.

Submitting ACH Reversals

Follow these steps to submit an ACH Reversal in the Sandbox environment:

1. Verify an Eligible Transaction Exists:
   1. For ACH transactions:
      1. Reversals can be initiated on only Newline-originated ACH transactions.
      2. The originated ACH must be in a status of settled.
      3. The reversal request must be submitted within 5 business banking days of the original payment’s settlement date.
   2. Use the GET list transactions endpoint to search for potential transactions eligible for ACH reversal. Once identified, use the GET a single transaction endpoint to verify the transaction's status and confirm its eligibility for reversal.
2. Post the Return Request:
   1. Leave the ACH Object blank in the Returns Endpoint request.
   2. Use the Post Create a New Return endpoint to submit your ACH return request, including the transaction UID.
3. A new transaction will be created. The transaction type will be an “initiated_ach_reversal".
   1. Confirm the return transaction's creation by using the Get List Returns or Get a Single Return endpoint to view the return's status and details.
4. Monitor Return Status:
   1. The return transaction will move through the following statuses:
      1. queued
      2. pending
      3. settled

Qualifying Criteria for ACH reversals:

NACHA guidelines determine when an ACH reversal of an originated payment can be submitted. The following criteria must be applied by Clients before submitting an ACH reversal request.

• The original payment was for an incorrect amount.
• The account number was entered incorrectly.
• Duplicate transactions occurred.

Submitting ACH and Wire Returns

Follow these steps to initiate an ACH or Wire return in the Sandbox environment:

1. Verify an Eligible Transaction Exists:
   1. For wires: Only received wire transactions are eligible. Create a wire transaction via the mock transactions endpoint if needed before proceeding. The wire transaction must be in a status of settled.
   2. For ACH transactions: Only externally-originated ACH transactions can be returned. Create an ACH transaction via the mock transactions endpoint if needed before proceeding.
      1. The ACH transaction must be in a status of settled. ACH return windows are time bound based on the SEC code of the ACH transaction being returned. Please see our API Error Code Documentation for guidance.
   3. Use the GET list transactions endpoint to search for potential transactions eligible for ACH reversal. Once identified, use the GET a single transaction endpoint to verify the transaction's status and confirm its eligibility for reversal.
2. Post the Return Request:
   1. Submit a return by providing the transaction UID of the transaction to be returned.
   2. A new return transaction will be created. The transaction type will indicate an “initiated” return (e.g., initiated_ach_return) to differentiate from received returns (e.g., ach_return).
   3. Use the Post Create a New Return endpoint to submit your ACH return request, including the transaction UID.
3. A new transaction will be created. The transaction type will be an “initiated_ach_reversal".
   1. Confirm the return transaction's creation by using the Get List Returns or Get a Single Return endpoint to view the return's status and details.
4. Monitor Return Status:
   1. The return transaction will move through the following statuses:
      1. queued
      2. pending
      3. settled

Initiating a Failed Return in Sandbox

To simulate a failed return:

1. Post a Return Request:
   1. Provide the transaction UID for the transaction you want to return.
2. Trigger Failure:
   1. Include the value "fail" in one of the free-text fields of the return request payload to simulate a failed return.
3. Status Update:
   1. The return transaction will show a status of failed.
   2. View the status by using the Get List Returns or Get a Single Return endpoints to view the return's status and details.

Error Handing for Returns

Below are common error responses for the Returns Endpoint. Each error indicates a specific condition to be addressed before resubmitting the request.

For complete details, visit the Error Codes Documentation.