Submit ACH Return

curl --request POST \
  --url https://api.example.com/ach-returns \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customer_id": "<string>",
  "loan_id": "<string>",
  "payment_id": "<string>",
  "system_source": "<string>",
  "payment_date": "2023-12-25",
  "payment_amount": 123,
  "payment_type": "<string>",
  "payment_reversed": true,
  "payment_reverse_date": "2023-12-25",
  "payment_reverse_reason_code": "<string>",
  "payment_reverse_comments": "<string>",
  "ach_submitted_date": "2023-12-25",
  "ach_settlement_date": "2023-12-25",
  "ach_return_code": "<string>",
  "ach_return_date": "2023-12-25",
  "ach_return_reason": "<string>",
  "ach_correction_code": "<string>",
  "ach_corrected_aba_number": "<string>",
  "ach_corrected_account_number": "<string>",
  "ach_correction_date": "2023-12-25",
  "debit_status": "<string>",
  "debit_decline_reason": "<string>",
  "overall_return_code": "<string>"
}
'

{
  "success": true,
  "message": "ACH return processed successfully"
}

​

Overview

This endpoint receives ACH return information from external loan management systems (LMS) and updates the corresponding payment records in Finosu. It handles payment reversals, ACH returns, ACH corrections (NOC), and debit card declines. Note: For submitting multiple ACH returns in a single request, use the batch endpoint.

​

ID Mapping

The endpoint uses reference IDs to locate records:

• customer_id - Your customer reference ID
• loan_id - Your loan reference ID
• payment_id - Your payment reference ID

​

Request Body Fields

​

Identifiers (Required)

• customer_id - Customer reference ID from your LMS
• loan_id - Loan reference ID from your LMS
• payment_id - Payment reference ID from your LMS

​

Payment Transaction Fields

• system_source - Source system identifier (e.g., “ExternalLMS”)
• payment_date - Date payment was made
• payment_amount - Payment amount in dollars
• payment_type - Type of payment
• payment_reversed - Boolean indicating if payment was reversed
• payment_reverse_date - Date payment was reversed
• payment_reverse_reason_code - Code indicating reversal reason
• payment_reverse_comments - Additional comments about the reversal

​

ACH Transaction Fields

• ach_submitted_date - Date ACH transaction was submitted
• ach_settlement_date - Date ACH transaction settled
• ach_status - ACH transaction status (PENDING, SUBMITTED, PROCESSED, COMPLETED, FAILED, RETURNED, CANCELED)

​

ACH Return Information

• ach_return_code - ACH return code (R01-R29)
• ach_return_date - Date of ACH return
• ach_return_reason - Human-readable return reason

​

ACH Correction (NOC - Notification of Change)

• ach_correction_code - ACH correction code from NOC
• ach_corrected_aba_number - Corrected ABA routing number
• ach_corrected_account_number - Corrected account number
• ach_correction_date - Date correction was received

​

Debit Card Fields

• debit_status - Debit card transaction status
• debit_decline_reason - Reason for debit card decline

​

Combined Fields

• overall_return_code - Combined return code from ACH or debit

​

What the Endpoint Does

When you submit ACH return information, Finosu:

1. Locates the records using the external reference IDs
2. Updates PaymentTransaction with:
   • Payment reversal information (if applicable)
   • Status change to RETURNED if ACH return exists
3. Updates AchPayment (if exists) with:
   • ACH transaction dates
   • Status mapping from your external status
4. Creates ACHReturnHistory record with:
   • ACH return code and reason
   • ACH correction/NOC data
   • Risk assessment tracking
   • Action taken metadata

​

Response

The endpoint returns a success response:

• success - Boolean indicating success
• message - Success or error message

​

Example Usage

This endpoint is typically called by external LMS systems when they detect ACH returns, payment reversals, or receive NOC (Notification of Change) records from banks.

​

Error Handling

The endpoint will return appropriate HTTP status codes:

• 200 OK - Successfully processed ACH return information
• 404 NOT FOUND - Customer, loan, or payment not found with provided IDs
• 422 UNPROCESSABLE ENTITY - ACH payment has no associated payment method
• 500 INTERNAL SERVER ERROR - Server error during processing