Record External Payment

Record a settled external payment

curl --request POST \
  --url https://api.finosu.com/external-payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "loanId": "ACCOUNT-1001",
  "transactionId": "lms-payment-001",
  "sourceSystem": "example-lms",
  "amount": "125.25",
  "currency": "USD",
  "paymentDate": "2026-10-16",
  "status": "settled",
  "settlesLoan": false
}
'

import requests

url = "https://api.finosu.com/external-payments"

payload = {
    "loanId": "ACCOUNT-1001",
    "transactionId": "lms-payment-001",
    "sourceSystem": "example-lms",
    "amount": "125.25",
    "currency": "USD",
    "paymentDate": "2026-10-16",
    "status": "settled",
    "settlesLoan": False
}
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({
    loanId: 'ACCOUNT-1001',
    transactionId: 'lms-payment-001',
    sourceSystem: 'example-lms',
    amount: '125.25',
    currency: 'USD',
    paymentDate: '2026-10-16',
    status: 'settled',
    settlesLoan: false
  })
};

fetch('https://api.finosu.com/external-payments', 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/external-payments",
  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([
    'loanId' => 'ACCOUNT-1001',
    'transactionId' => 'lms-payment-001',
    'sourceSystem' => 'example-lms',
    'amount' => '125.25',
    'currency' => 'USD',
    'paymentDate' => '2026-10-16',
    'status' => 'settled',
    'settlesLoan' => false
  ]),
  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/external-payments"

	payload := strings.NewReader("{\n  \"loanId\": \"ACCOUNT-1001\",\n  \"transactionId\": \"lms-payment-001\",\n  \"sourceSystem\": \"example-lms\",\n  \"amount\": \"125.25\",\n  \"currency\": \"USD\",\n  \"paymentDate\": \"2026-10-16\",\n  \"status\": \"settled\",\n  \"settlesLoan\": false\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/external-payments")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"loanId\": \"ACCOUNT-1001\",\n  \"transactionId\": \"lms-payment-001\",\n  \"sourceSystem\": \"example-lms\",\n  \"amount\": \"125.25\",\n  \"currency\": \"USD\",\n  \"paymentDate\": \"2026-10-16\",\n  \"status\": \"settled\",\n  \"settlesLoan\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.finosu.com/external-payments")

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  \"loanId\": \"ACCOUNT-1001\",\n  \"transactionId\": \"lms-payment-001\",\n  \"sourceSystem\": \"example-lms\",\n  \"amount\": \"125.25\",\n  \"currency\": \"USD\",\n  \"paymentDate\": \"2026-10-16\",\n  \"status\": \"settled\",\n  \"settlesLoan\": false\n}"

response = http.request(request)
puts response.read_body

{
  "paymentTransactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "transactionId": "<string>",
  "loanId": "<string>",
  "amount": "<string>",
  "currency": "USD",
  "paymentDate": "2023-12-25",
  "status": "recorded",
  "replayed": true,
  "overpayment": true,
  "settledLoan": true
}

{
  "paymentTransactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "transactionId": "<string>",
  "loanId": "<string>",
  "amount": "<string>",
  "currency": "USD",
  "paymentDate": "2023-12-25",
  "status": "recorded",
  "replayed": true,
  "overpayment": true,
  "settledLoan": true
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

POST

external-payments

Record a settled external payment

curl --request POST \
  --url https://api.finosu.com/external-payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "loanId": "ACCOUNT-1001",
  "transactionId": "lms-payment-001",
  "sourceSystem": "example-lms",
  "amount": "125.25",
  "currency": "USD",
  "paymentDate": "2026-10-16",
  "status": "settled",
  "settlesLoan": false
}
'

import requests

url = "https://api.finosu.com/external-payments"

payload = {
    "loanId": "ACCOUNT-1001",
    "transactionId": "lms-payment-001",
    "sourceSystem": "example-lms",
    "amount": "125.25",
    "currency": "USD",
    "paymentDate": "2026-10-16",
    "status": "settled",
    "settlesLoan": False
}
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({
    loanId: 'ACCOUNT-1001',
    transactionId: 'lms-payment-001',
    sourceSystem: 'example-lms',
    amount: '125.25',
    currency: 'USD',
    paymentDate: '2026-10-16',
    status: 'settled',
    settlesLoan: false
  })
};

fetch('https://api.finosu.com/external-payments', 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/external-payments",
  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([
    'loanId' => 'ACCOUNT-1001',
    'transactionId' => 'lms-payment-001',
    'sourceSystem' => 'example-lms',
    'amount' => '125.25',
    'currency' => 'USD',
    'paymentDate' => '2026-10-16',
    'status' => 'settled',
    'settlesLoan' => false
  ]),
  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/external-payments"

	payload := strings.NewReader("{\n  \"loanId\": \"ACCOUNT-1001\",\n  \"transactionId\": \"lms-payment-001\",\n  \"sourceSystem\": \"example-lms\",\n  \"amount\": \"125.25\",\n  \"currency\": \"USD\",\n  \"paymentDate\": \"2026-10-16\",\n  \"status\": \"settled\",\n  \"settlesLoan\": false\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/external-payments")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"loanId\": \"ACCOUNT-1001\",\n  \"transactionId\": \"lms-payment-001\",\n  \"sourceSystem\": \"example-lms\",\n  \"amount\": \"125.25\",\n  \"currency\": \"USD\",\n  \"paymentDate\": \"2026-10-16\",\n  \"status\": \"settled\",\n  \"settlesLoan\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.finosu.com/external-payments")

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  \"loanId\": \"ACCOUNT-1001\",\n  \"transactionId\": \"lms-payment-001\",\n  \"sourceSystem\": \"example-lms\",\n  \"amount\": \"125.25\",\n  \"currency\": \"USD\",\n  \"paymentDate\": \"2026-10-16\",\n  \"status\": \"settled\",\n  \"settlesLoan\": false\n}"

response = http.request(request)
puts response.read_body

{
  "paymentTransactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "transactionId": "<string>",
  "loanId": "<string>",
  "amount": "<string>",
  "currency": "USD",
  "paymentDate": "2023-12-25",
  "status": "recorded",
  "replayed": true,
  "overpayment": true,
  "settledLoan": true
}

{
  "paymentTransactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "transactionId": "<string>",
  "loanId": "<string>",
  "amount": "<string>",
  "currency": "USD",
  "paymentDate": "2023-12-25",
  "status": "recorded",
  "replayed": true,
  "overpayment": true,
  "settledLoan": true
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Use this endpoint when your lender or loan management system (LMS) collected a payment outside Finosu and the money has already settled. Finosu records and applies the payment; it does not create an ACH/card processor charge. This is different from Confirm ACH Settlement, which updates a payment that Finosu already originated.

Authentication and account identity

Send the company API key in X-API-Key. The key determines the company scope; company or customer IDs in the request cannot widen it. loanId is required and must be the exact company-owned external loan/account identifier. A customer identifier is not accepted because one customer can have multiple loans. Unknown or other-company identifiers return 404. If legacy data makes an identifier ambiguous within the authenticated company, Finosu returns 409 and records nothing.

Request

{
  "loanId": "ACCOUNT-1001",
  "transactionId": "lms-payment-001",
  "sourceSystem": "example-lms",
  "amount": "125.25",
  "currency": "USD",
  "paymentDate": "2026-10-16",
  "status": "settled",
  "settlesLoan": false
}

transactionId is the lender’s stable transaction identity. It must be unique across every feed used by the authenticated company, not merely within one loan.
sourceSystem is a stable lowercase LMS identifier using letters, digits, ., _, or -. Finosu stores it as payment provenance.
amount is a positive USD decimal no greater than 21474836.47, with at most two fractional digits. JSON strings are recommended to preserve decimal precision.
paymentDate is the settlement date in ISO YYYY-MM-DD format.
status must be settled. Pending, submitted, failed, returned, reversed, or refunded events are not accepted by this contract.
Set settlesLoan to true only after the lender has finalized this payment as full payoff or negotiated settlement. It invokes the existing external settlement flow, including stopping servicing and pending communications.

CamelCase is preferred. Matching snake_case field names remain accepted. Extra fields are rejected.

Idempotency and conflicts

No separate idempotency header is needed. Finosu atomically claims (authenticated company, transactionId) in the payment transaction itself.

The first accepted request returns 201 and status: "recorded".
An exact retry returns 200, the original paymentTransactionId, and status: "duplicate". It does not apply money or settlement effects again.
Reusing the same transactionId with a changed loan, source, amount, date, currency, status, or settlesLoan value returns 409. The original payment remains unchanged.

The database uniqueness claim is race-safe, so simultaneous exact retries produce one payment.

Accounting and integration behavior

The payment is stored as a successful EXTERNAL_IMPORT transaction and uses the same scheduled-payment allocation and external-settlement services as the canonical CSV flow. Rollover rows may be created when one payment covers multiple installments, but their total equals the request amount. Finosu does not create an AchPayment, payment method, gateway transaction, or processor charge. Imports dated before boarding remain pre-boarding history and are not allocated to a later Finosu payment plan. Existing balance calculations exclude that history where the transferred balance already includes it, preventing double counting. Post-boarding imports participate in normal balance, reporting, and payoff calculations. EXTERNAL_IMPORT payments are ineligible for LMS payment writeback. The stored source provenance also identifies the originating LMS, preventing the import from being echoed back as a new Finosu-originated payment.

Response

{
  "paymentTransactionId": "17f82780-3c2d-4e71-bbad-03ca7f713e4f",
  "transactionId": "lms-payment-001",
  "loanId": "ACCOUNT-1001",
  "amount": "125.25",
  "currency": "USD",
  "paymentDate": "2026-10-16",
  "status": "recorded",
  "replayed": false,
  "overpayment": false,
  "settledLoan": false
}

Returns, reversals, and corrections

Do not represent a return, reversal, or correction by sending a negative amount or by reusing transactionId with changed data; both are rejected. The existing /ach-returns API is only for ACH payments Finosu originated and is not a general reversal API. Until a separate immutable external-adjustment contract is published, contact Finosu support for a reviewed correction. This endpoint never deletes or edits an existing financial record.

Errors

401 — missing, invalid, or inactive X-API-Key
404 — loanId is not owned by the authenticated company
409 — ambiguous loanId, or conflicting reuse of transactionId
422 — invalid identifier, amount, currency, date, status, or request shape
500 — the atomic payment/accounting operation failed and was rolled back

Authorizations

X-API-Key

string

header

required

Body

application/json

A successful payment already settled outside Finosu. CamelCase is preferred; matching snake_case aliases are accepted. Extra fields are rejected.

loanId

string

required

Exact company-owned external loan/account identifier.

Required string length: 1 - 255

transactionId

string

required

Stable lender transaction identity, unique across the authenticated company.

Required string length: 1 - 200

sourceSystem

string

required

Stable lowercase identifier of the originating LMS.

Required string length: 1 - 50

Pattern: ^[a-z0-9][a-z0-9._-]*$

amount

string<decimal>

required

Positive USD amount no greater than 21474836.47, with at most two decimal places.

Pattern: ^(?!0+(?:\.0{1,2})?$)\d{1,8}(?:\.\d{1,2})?$

currency

enum<string>

required

Available options:

USD

paymentDate

string<date>

required

Settlement date in YYYY-MM-DD format.

status

enum<string>

required

Available options:

settled

settlesLoan

boolean

default:false

True only for a lender-finalized full payoff or negotiated settlement.

Response

Exact idempotent replay; no accounting or settlement effects were repeated.

paymentTransactionId

string<uuid>

required

transactionId

string

required

loanId

string

required

amount

string<decimal>

required

currency

enum<string>

required

Available options:

USD

paymentDate

string<date>

required

status

enum<string>

required

Available options:

recorded,

duplicate

replayed

boolean

required

overpayment

boolean

required

settledLoan

boolean

required

API Documentation

Core Resources

Origination

Collections

Record External Payment

Authentication and account identity

Request

Idempotency and conflicts

Accounting and integration behavior

Response

Returns, reversals, and corrections

Errors

Authorizations

Body

Response

​Authentication and account identity

​Request

​Idempotency and conflicts

​Accounting and integration behavior

​Response

​Returns, reversals, and corrections

​Errors

Authorizations

Body

Response

Authentication and account identity

Request

Idempotency and conflicts

Accounting and integration behavior

Response

Returns, reversals, and corrections

Errors