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 settlement confirmation from external loan management systems (LMS) and marks the corresponding ACH payment as COMPLETED and payment transaction as SUCCESSFUL. Note: For submitting multiple ACH confirmations 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

Settlement Fields

  • settlementDate - Date the ACH payment settled

What the Endpoint Does

When you submit ACH settlement confirmation, Finosu:
  1. Locates the records using the external reference IDs
  2. Updates AchPayment with:
    • Status set to COMPLETED
    • Settlement date (if provided)
  3. Updates PaymentTransaction with:
    • Status set to SUCCESSFUL

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 confirm that an ACH payment has successfully settled at the bank.

Error Handling

The endpoint will return appropriate HTTP status codes:
  • 200 OK - Successfully confirmed ACH settlement
  • 422 UNPROCESSABLE CONTENT - ACH payment does not belong to specified loan
  • 404 NOT FOUND - Customer, loan, or payment not found with provided IDs
  • 409 CONFLICT - Multiple ACH payments found with the same processor transaction ID
  • 500 INTERNAL SERVER ERROR - Server error during processing
Authentication failures return 401; invalid request structure returns 422.

Authorizations

X-API-Key
string
header
required

Body

application/json

Request schema for ACH settlement confirmation from external LMS.

Maps to the same ID conventions as ACH returns. 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.

settlementDate
string<date-time> | null

Date the ACH payment settled

Response

Payment update recorded.

Response schema for ACH settlement confirmation.

success
boolean
required

Whether the confirmation was successful

message
string
required

Success or error message