> ## 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 Returns (Batch)

> Submit multiple ACH return records in a single batch request. Each return is processed independently with detailed individual results.

## Overview

This batch endpoint allows you to submit multiple ACH return records from external loan management systems (LMS) in a single API request for improved efficiency.

Each return in the batch is processed independently with detailed individual results, making it ideal for processing daily ACH return files from banks or bulk syncing from your LMS system.

## ID Mapping

The endpoint uses the same reference ID mapping as the single ACH return endpoint:

* **customer\_id** - Maps to `customer.reference_id`
* **loan\_id** - Maps to `loan.external_reference`
* **payment\_id** - Maps to `payment_transaction.external_reference`

## Request Body Format

The batch endpoint accepts an array of ACH return records wrapped in a `returns` field:

```json theme={null}
{
  "returns": [
    {
      "customer_id": "CUST123",
      "loan_id": "LOAN456",
      "payment_id": "PMT789",
      "payment_date": "2024-01-15T10:00:00Z",
      "payment_amount": "100.00",
      "ach_return_code": "R01",
      "ach_return_date": "2024-01-18T10:00:00Z",
      "ach_return_reason": "Insufficient Funds"
    },
    {
      "customer_id": "CUST124",
      "loan_id": "LOAN457",
      "payment_id": "PMT790",
      "payment_date": "2024-01-15T10:00:00Z",
      "payment_amount": "150.00",
      "ach_return_code": "R03",
      "ach_return_date": "2024-01-18T10:00:00Z",
      "ach_return_reason": "No Account/Unable to Locate Account"
    }
  ]
}
```

### Individual Return Schema

Each object in the `returns` array follows the same schema as the [single ACH return endpoint](./create.mdx):

**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
* `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

**ACH Transaction Fields:**

* `ach_submitted_date` - Date ACH was submitted
* `ach_settlement_date` - Date ACH settled
* `ach_status` - ACH 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):**

* `ach_correction_code` - ACH correction code
* `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

## Response Format

The batch endpoint returns detailed results for each ACH return processed:

```json theme={null}
{
  "success": true,
  "total_processed": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "success": true,
      "payment_id": "PMT789",
      "message": "ACH return information successfully recorded"
    },
    {
      "success": true,
      "payment_id": "PMT790",
      "message": "ACH return information successfully recorded"
    }
  ]
}
```

### Response Fields

* **success** - `true` if ALL returns were processed successfully, `false` if any failed
* **total\_processed** - Total number of returns in the batch
* **successful** - Number of successfully processed returns
* **failed** - Number of failed returns
* **results** - Array of individual results for each return
  * **success** - Whether this specific return was processed successfully
  * **payment\_id** - The payment ID from the request for easy matching
  * **message** - Success or error message for this specific return

## Partial Success Handling

The batch endpoint uses **partial success** handling to ensure maximum processing:

* **Individual failures don't stop processing** - If one return fails, the remaining returns are still processed
* **Detailed error messages** - Each failed return includes its specific error message
* **Transaction isolation** - Each return is processed in its own transaction to prevent one failure from affecting others
* **Overall success flag** - The top-level `success` field is `true` only if all returns succeeded

### Example: Partial Failure Response

```json theme={null}
{
  "success": false,
  "total_processed": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "success": true,
      "payment_id": "PMT789",
      "message": "ACH return information successfully recorded"
    },
    {
      "success": false,
      "payment_id": "PMT790",
      "message": "404: Customer with reference_id 'CUST999' not found"
    },
    {
      "success": true,
      "payment_id": "PMT791",
      "message": "ACH return information successfully recorded"
    }
  ]
}
```

## What the Endpoint Does

For each ACH return in the batch, 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

5. **Triggers NSF revocation check** (for R01/R09 returns):
   * Automatically revokes payment methods after 2 consecutive NSF returns

## When to Use Batch vs Single

**Use the batch endpoint when:**

* Processing daily ACH return files from your bank
* Syncing multiple returns from your LMS system
* You have more than 5-10 returns to submit
* You want to minimize API calls for efficiency

**Use the [single endpoint](./create.mdx) when:**

* Processing real-time individual returns
* You only have 1-2 returns to submit
* You need simpler error handling
* Testing or debugging individual returns

## Error Handling

The endpoint returns HTTP status 200 OK for all requests, with detailed success/failure information in the response body for each individual return.

**Individual return errors may include:**

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

Check the `results` array in the response to see which returns succeeded and which failed.

## Authentication

Authentication via **X-API-Key header**:

* API key is company-scoped
* Must be obtained from Finosu
* Same authentication as single ACH return endpoint

## Example Usage

This endpoint is typically used for:

* **Daily bank reconciliation** - Process ACH return files from your bank
* **Bulk LMS sync** - Sync multiple return records from your loan management system
* **Scheduled jobs** - Automated daily/weekly return processing workflows


## OpenAPI

````yaml POST /ach-returns/batch
openapi: 3.1.0
info:
  title: Finosu API
  description: Finosu API
  license:
    name: MIT
  version: 1.0.0
servers: []
security:
  - apiKeyAuth: []
paths:
  /ach-returns/batch:
    post:
      description: >-
        Submit multiple ACH return records in a single batch request. Each
        return is processed independently with detailed individual results.
      requestBody:
        description: Batch of ACH return records
        content:
          application/json:
            schema:
              type: object
              required:
                - returns
              properties:
                returns:
                  type: array
                  description: Array of ACH return records to process
                  items:
                    $ref: '#/components/schemas/AchReturnRequest'
        required: true
      responses:
        '200':
          description: >-
            Batch processing completed (may include partial failures - check
            individual results)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: >-
                      True if ALL returns were processed successfully, false if
                      any failed
                    example: true
                  total_processed:
                    type: integer
                    description: Total number of returns in the batch
                    example: 2
                  successful:
                    type: integer
                    description: Number of successfully processed returns
                    example: 2
                  failed:
                    type: integer
                    description: Number of failed returns
                    example: 0
                  results:
                    type: array
                    description: Individual results for each return
                    items:
                      type: object
                      properties:
                        success:
                          type: boolean
                          description: >-
                            Whether this specific return was processed
                            successfully
                        payment_id:
                          type: string
                          description: The payment ID from the request for easy matching
                        message:
                          type: string
                          description: Success or error message for this specific return
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
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````