Skip to main content
POST
cURL

Request field names

Use camelCase request fields. Legacy snake_case names remain accepted, including within batches. If both names for a field are supplied, the camelCase value takes precedence. Response field names remain unchanged.

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:
  • customerId - Your customer reference ID
  • loanId - Your loan reference ID
  • paymentId - Maps to the ACH payment’s processor transaction ID
Date/time fields accept ISO 8601 timestamps, for example 2026-09-30T12:00:00Z. Optional date/time fields may be omitted or null.

Request Body Format

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

Individual Return Schema

Each object in the returns array follows the same schema as the single ACH return endpoint: Identifiers (Required):
  • customerId - Customer reference ID from your LMS
  • loanId - Loan reference ID from your LMS
  • paymentId - The processor transaction ID for the ACH payment
Payment Transaction Fields:
  • systemSource - Source system identifier
  • paymentDate - Date payment was made
  • paymentAmount - Payment amount in dollars, as a JSON number or decimal string
  • paymentType - Type of payment
  • paymentReversed - Boolean indicating if payment was reversed
  • paymentReverseDate - Date payment was reversed
  • paymentReverseReasonCode - Code indicating reversal reason
  • paymentReverseComments - Additional comments
ACH Transaction Fields:
  • achSubmittedDate - Date ACH was submitted
  • achSettlementDate - Date ACH settled
  • achStatus - External ACH status; numeric values and strings are accepted, with integration-specific mapping
ACH Return Information:
  • achReturnCode - ACH return code, such as R01
  • achReturnDate - Date of ACH return
  • achReturnReason - Human-readable return reason
ACH Correction (NOC):
  • achCorrectionCode - ACH correction code
  • achCorrectedAbaNumber - Corrected ABA routing number
  • achCorrectedAccountNumber - Corrected account number
  • achCorrectionDate - Date correction was received
Debit Card Fields:
  • debitStatus - Debit card transaction status
  • debitDeclineReason - Reason for debit card decline
Combined Fields:
  • overallReturnCode - Combined return code from ACH or debit

Response Format

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

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

payment_method_disabled in the response is a boolean or null when not applicable.

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 when return information is present, 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 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

A valid, authenticated batch returns HTTP status 200 OK, 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 CONTENT - ACH payment does not belong to the specified loan, or 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
Authentication failures return 401; invalid request structure returns 422. A 200 batch response does not mean every item succeeded; inspect success, successful, failed, and each entry in results. Item failures are reported in the response body rather than as the HTTP status of the entire batch. An active return-note delivery can cause an item to fail with a 503 message while the batch response remains 200. Retry the failed item later. A validation failure for an individual payment is reported with a 422: message prefix in its result; the batch HTTP status remains 200. Unexpected processing failures use a Failed to process ACH return: message prefix without a status-code prefix. Inspect each item’s success value; do not rely on numeric message prefixes alone.

Authorizations

X-API-Key
string
header
required

Body

application/json

Batch request schema for multiple ACH returns from external LMS. Accepts an array of ACH return records for efficient bulk processing. Use camelCase fields; legacy snake_case aliases are also accepted. If both spellings are supplied, camelCase takes precedence.

returns
object[]
required

Array of ACH return records to process

Response

Batch processing results.

Response schema for batch ACH return submission.

success
boolean
required

Whether all returns were processed successfully

total_processed
integer
required

Total number of returns processed

successful
integer
required

Number of successfully processed returns

failed
integer
required

Number of failed returns

results
object[]
required

Individual results for each return