> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finosu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit ACH Return

> Submit ACH return information from external loan management systems (LMS) and update corresponding payment records in Finosu

## 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](./batch.mdx).

## 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


## OpenAPI

````yaml POST /ach-returns
openapi: 3.1.0
info:
  title: Finosu API
  description: Finosu API
  license:
    name: MIT
  version: 1.0.0
servers: []
security:
  - apiKeyAuth: []
paths:
  /ach-returns:
    post:
      description: >-
        Submit ACH return information from external loan management systems
        (LMS) and update corresponding payment records in Finosu
      requestBody:
        description: ACH return data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AchReturnRequest'
        required: true
      responses:
        '200':
          description: Successfully processed ACH return information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: ACH return processed successfully
        '404':
          description: Customer, loan, or payment not found with provided IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error during processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AchReturnRequest:
      type: object
      required:
        - customer_id
        - loan_id
        - payment_id
      properties:
        customer_id:
          type: string
          description: External customer reference ID from your LMS
        loan_id:
          type: string
          description: External loan reference ID from your LMS
        payment_id:
          type: string
          description: External payment reference ID from your LMS
        system_source:
          type: string
          description: Source system identifier (e.g., 'ExternalLMS')
        payment_date:
          type: string
          format: date
          description: Date payment was made
        payment_amount:
          type: number
          description: Payment amount in dollars
        payment_type:
          type: string
          description: Type of payment
        payment_reversed:
          type: boolean
          description: Boolean indicating if payment was reversed
        payment_reverse_date:
          type: string
          format: date
          description: Date payment was reversed
        payment_reverse_reason_code:
          type: string
          description: Code indicating reversal reason
        payment_reverse_comments:
          type: string
          description: Additional comments about the reversal
        ach_submitted_date:
          type: string
          format: date
          description: Date ACH transaction was submitted
        ach_settlement_date:
          type: string
          format: date
          description: Date ACH transaction settled
        ach_status:
          type: string
          enum:
            - PENDING
            - SUBMITTED
            - COMPLETED
            - FAILED
            - RETURNED
          description: ACH transaction status
        ach_return_code:
          type: string
          description: ACH return code (R01-R29)
        ach_return_date:
          type: string
          format: date
          description: Date of ACH return
        ach_return_reason:
          type: string
          description: Human-readable return reason
        ach_correction_code:
          type: string
          description: ACH correction code from NOC
        ach_corrected_aba_number:
          type: string
          description: Corrected ABA routing number
        ach_corrected_account_number:
          type: string
          description: Corrected account number
        ach_correction_date:
          type: string
          format: date
          description: Date correction was received
        debit_status:
          type: string
          description: Debit card transaction status
        debit_decline_reason:
          type: string
          description: Reason for debit card decline
        overall_return_code:
          type: string
          description: Combined return code from ACH or debit
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````