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 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:
  • customerId - Your customer reference ID
  • loanId - Your loan reference ID
  • paymentId - The payment 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 Fields

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 (e.g., “ExternalLMS”)
  • 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 about the reversal

ACH Transaction Fields

  • achSubmittedDate - Date ACH transaction was submitted
  • achSettlementDate - Date ACH transaction 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 - Notification of Change)

  • achCorrectionCode - ACH correction code from NOC
  • 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
payment_method_disabled in the response is a boolean or null when not applicable.

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 when return information is present, 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
  • 409 CONFLICT - Multiple matching ACH payments
  • 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
Authentication failures return 401; invalid request structure returns 422. A 503 Service Unavailable response means return-note delivery is already in progress. Retry the request later.

Authorizations

X-API-Key
string
header
required

Body

application/json

Request schema for ACH return information from external LMS.

Maps to SQL query fields from external LMS system. Use camelCase fields; legacy snake_case aliases are also accepted. If both spellings are supplied, camelCase takes precedence.

customerId
string
required

External customer reference ID

loanId
string
required

External loan reference ID

paymentId
string
required

Payment processor transaction ID for the ACH payment.

systemSource
string | null

Source system identifier

paymentDate
string<date-time> | null

Date payment was made

paymentReverseDate
string<date-time> | null

Date payment was reversed

paymentReversed
boolean | null

Whether payment was reversed

paymentReverseReasonCode
string | null

Code for payment reversal reason

paymentReverseComments
string | null

Comments about payment reversal

paymentType
string | null

Type of payment

paymentAmount

Payment amount

achSubmittedDate
string<date-time> | null

Date ACH was submitted

achSettlementDate
string<date-time> | null

Date ACH settled

achStatus

External ACH status. Numeric values and numeric strings are normalized to integer strings. Status mapping depends on the integration; this is not a closed enum.

achReturnCode
string | null

ACH return code

achReturnDate
string<date-time> | null

Date of ACH return

achReturnReason
string | null

Reason for ACH return

achCorrectionCode
string | null

ACH correction code from NOC

achCorrectedAbaNumber
string | null

Corrected ABA routing number

achCorrectedAccountNumber
string | null

Corrected account number

achCorrectionDate
string<date-time> | null

Date correction was received

debitStatus
string | null

Debit card transaction status

debitDeclineReason
string | null

Reason for debit card decline

overallReturnCode
string | null

Combined return code

isMetadataError
boolean
default:false

Set to true to indicate this is a permanent metadata error that should deactivate the payment method

Response

Payment update recorded.

Response schema for ACH return information submission.

success
boolean
required

Whether the submission was successful

message
string
required

Success or error message

payment_method_disabled
boolean | null

Whether processing disabled the payment method; null when not applicable.