cURL
curl --request POST \
--url https://api.finosu.com/ach-confirms/batch \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"confirms": [
{
"customerId": "<string>",
"loanId": "<string>",
"paymentId": "<string>",
"settlementDate": "2023-11-07T05:31:56Z"
}
]
}
'import requests
url = "https://api.finosu.com/ach-confirms/batch"
payload = { "confirms": [
{
"customerId": "<string>",
"loanId": "<string>",
"paymentId": "<string>",
"settlementDate": "2023-11-07T05:31:56Z"
}
] }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
confirms: [
{
customerId: '<string>',
loanId: '<string>',
paymentId: '<string>',
settlementDate: '2023-11-07T05:31:56Z'
}
]
})
};
fetch('https://api.finosu.com/ach-confirms/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.finosu.com/ach-confirms/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'confirms' => [
[
'customerId' => '<string>',
'loanId' => '<string>',
'paymentId' => '<string>',
'settlementDate' => '2023-11-07T05:31:56Z'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.finosu.com/ach-confirms/batch"
payload := strings.NewReader("{\n \"confirms\": [\n {\n \"customerId\": \"<string>\",\n \"loanId\": \"<string>\",\n \"paymentId\": \"<string>\",\n \"settlementDate\": \"2023-11-07T05:31:56Z\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.finosu.com/ach-confirms/batch")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"confirms\": [\n {\n \"customerId\": \"<string>\",\n \"loanId\": \"<string>\",\n \"paymentId\": \"<string>\",\n \"settlementDate\": \"2023-11-07T05:31:56Z\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.finosu.com/ach-confirms/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"confirms\": [\n {\n \"customerId\": \"<string>\",\n \"loanId\": \"<string>\",\n \"paymentId\": \"<string>\",\n \"settlementDate\": \"2023-11-07T05:31:56Z\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"total_processed": 123,
"successful": 123,
"failed": 123,
"results": [
{
"success": true,
"payment_id": "<string>",
"message": "<string>"
}
]
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}Payments
Confirm ACH Settlements (Batch)
Process a batch independently and inspect each result; HTTP 200 does not mean every item succeeded.
POST
/
ach-confirms
/
batch
cURL
curl --request POST \
--url https://api.finosu.com/ach-confirms/batch \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"confirms": [
{
"customerId": "<string>",
"loanId": "<string>",
"paymentId": "<string>",
"settlementDate": "2023-11-07T05:31:56Z"
}
]
}
'import requests
url = "https://api.finosu.com/ach-confirms/batch"
payload = { "confirms": [
{
"customerId": "<string>",
"loanId": "<string>",
"paymentId": "<string>",
"settlementDate": "2023-11-07T05:31:56Z"
}
] }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
confirms: [
{
customerId: '<string>',
loanId: '<string>',
paymentId: '<string>',
settlementDate: '2023-11-07T05:31:56Z'
}
]
})
};
fetch('https://api.finosu.com/ach-confirms/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.finosu.com/ach-confirms/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'confirms' => [
[
'customerId' => '<string>',
'loanId' => '<string>',
'paymentId' => '<string>',
'settlementDate' => '2023-11-07T05:31:56Z'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.finosu.com/ach-confirms/batch"
payload := strings.NewReader("{\n \"confirms\": [\n {\n \"customerId\": \"<string>\",\n \"loanId\": \"<string>\",\n \"paymentId\": \"<string>\",\n \"settlementDate\": \"2023-11-07T05:31:56Z\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.finosu.com/ach-confirms/batch")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"confirms\": [\n {\n \"customerId\": \"<string>\",\n \"loanId\": \"<string>\",\n \"paymentId\": \"<string>\",\n \"settlementDate\": \"2023-11-07T05:31:56Z\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.finosu.com/ach-confirms/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"confirms\": [\n {\n \"customerId\": \"<string>\",\n \"loanId\": \"<string>\",\n \"paymentId\": \"<string>\",\n \"settlementDate\": \"2023-11-07T05:31:56Z\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"total_processed": 123,
"successful": 123,
"failed": 123,
"results": [
{
"success": true,
"payment_id": "<string>",
"message": "<string>"
}
]
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}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 settlement confirmations from external loan management systems (LMS) in a single API request for improved efficiency. Each confirmation in the batch is processed independently with detailed individual results, making it ideal for processing daily ACH settlement files from banks or bulk syncing from your LMS system.ID Mapping
The endpoint uses the same reference ID mapping as the single ACH confirm endpoint. Date/time fields accept ISO 8601 timestamps, for example2026-09-30T12:00:00Z.
Optional date/time fields may be omitted or null.
Request Body Format
The batch endpoint accepts an array of ACH confirm records wrapped in aconfirms field:
{
"confirms": [
{
"customerId": "CUST123",
"loanId": "LOAN456",
"paymentId": "PMT789",
"settlementDate": "2024-01-17T09:00:00Z"
},
{
"customerId": "CUST124",
"loanId": "LOAN457",
"paymentId": "PMT790",
"settlementDate": "2024-01-17T09:00:00Z"
}
]
}
Individual Confirm Schema
Each object in theconfirms array follows the same schema as the single ACH confirm endpoint:
Identifiers (Required):
customerId- Customer reference ID from your LMSloanId- Loan reference ID from your LMSpaymentId- The processor transaction ID for the ACH payment
settlementDate- Date the ACH payment settled
Response Format
The batch endpoint returns detailed results for each ACH confirmation processed:{
"success": true,
"total_processed": 2,
"successful": 2,
"failed": 0,
"results": [
{
"success": true,
"payment_id": "PMT789",
"message": "ACH payment successfully confirmed as settled"
},
{
"success": true,
"payment_id": "PMT790",
"message": "ACH payment successfully confirmed as settled"
}
]
}
Response Fields
- success -
trueif ALL confirmations were processed successfully,falseif any failed - total_processed - Total number of confirmations in the batch
- successful - Number of successfully processed confirmations
- failed - Number of failed confirmations
- results - Array of individual results for each confirmation
- success - Whether this specific confirmation was processed successfully
- payment_id - The payment ID from the request for easy matching
- message - Success or error message for this specific confirmation
Partial Success Handling
The batch endpoint uses partial success handling to ensure maximum processing:- Individual failures don’t stop processing - If one confirmation fails, the remaining confirmations are still processed
- Detailed error messages - Each failed confirmation includes its specific error message
- Transaction isolation - Each confirmation is processed in its own transaction to prevent one failure from affecting others
- Overall success flag - The top-level
successfield istrueonly if all confirmations succeeded
Example: Partial Failure Response
{
"success": false,
"total_processed": 3,
"successful": 2,
"failed": 1,
"results": [
{
"success": true,
"payment_id": "PMT789",
"message": "ACH payment successfully confirmed as settled"
},
{
"success": false,
"payment_id": "PMT790",
"message": "404: Customer with reference_id 'CUST999' not found"
},
{
"success": true,
"payment_id": "PMT791",
"message": "ACH payment successfully confirmed as settled"
}
]
}
What the Endpoint Does
For each ACH confirmation in the batch, Finosu:- Locates the records using the external reference IDs
-
Updates AchPayment with:
- Status set to COMPLETED
- Settlement date (if provided)
-
Updates PaymentTransaction with:
- Status set to SUCCESSFUL
When to Use Batch vs Single
Use the batch endpoint when:- Processing daily ACH settlement files from your bank
- Syncing multiple confirmations from your LMS system
- You have more than 5-10 confirmations to submit
- You want to minimize API calls for efficiency
- Processing real-time individual confirmations
- You only have 1-2 confirmations to submit
- You need simpler error handling
- Testing or debugging individual confirmations
Error Handling
A valid, authenticated batch returns HTTP status 200 OK, with detailed success/failure information in the response body for each individual confirmation. Individual confirmation errors may include:- 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
results array in the response to see which confirmations 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 confirm endpoint
Example Usage
This endpoint is typically used for:- Daily bank reconciliation - Process ACH settlement files from your bank
- Bulk LMS sync - Sync multiple settlement confirmations from your loan management system
- Scheduled jobs - Automated daily/weekly settlement confirmation workflows
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.
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 confirm: message prefix without a status-code prefix. Inspect each item’s success value; do not rely on numeric message prefixes alone.Body
application/json
Batch request schema for multiple ACH confirmations from external LMS. Accepts an array of ACH confirm records for efficient bulk processing. Use camelCase fields; legacy snake_case aliases are also accepted. If both spellings are supplied, camelCase takes precedence.
Response
Batch processing results.
Response schema for batch ACH confirm submission.