Recipes›Lending›Take a one-time payment

Take a one-time payment

Create a borrower-authorized Harbor payment, distinguish rail settlement from value-dated ledger posting, inspect allocation on the posted transaction, and download the receipt only after the money is authoritative.

Time

~5 min plus settlement

Surface

LMS API

Steps

Gate

Authorization · restrictions · settlement

EndpointsPOST /v1/loans/{loanId}/paymentsGET /v1/loans/{loanId}/payments/{paymentId}GET /v1/loans/{loanId}/payments/{paymentId}/receipt

Use Maya’s verified instrument 704 to collect Harbor installment 1: $517.14, effective on its September 12 due date.

Create the payment intent

Borrower authorized

POST/v1/loans/7204/payments

effectiveDate is the business date on which credit should apply; it is not the provider settlement time. Creation is guarded: the amount plus any other in-flight intents may not exceed Harbor’s total outstanding, and an active PAYMENT_HOLD restriction blocks the request. The instrument must be ACTIVE and VERIFIED.

curl -X POST "$BASE/v1/loans/7204/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: harbor-installment-1-maya" \
  -d '{
    "instrumentId": 704,
    "amount": "517.14",
    "currency": "USD",
    "rail": "ACH",
    "effectiveDate": "2026-09-12",
    "source": "BORROWER"
  }'

{ "paymentId": 9011, "loanRef": "7204", "status": "CREATED", "attemptNumber": 1 }

A second request with a new idempotency key means a second intended debit—never generate a fresh key merely because a response timed out. Money creates bind the Idempotency-Key to a payload fingerprint: replaying the same key with a different body fails with 422.

Wait for authoritative posting

Value dated

GET/v1/loans/7204/payments/9011

CREATED, VALIDATED, SUBMITTED, and PROCESSING are in flight. SETTLED_PENDING_POST records the provider result; POSTED means the loan ledger now agrees.

curl "$BASE/v1/loans/7204/payments/9011" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender"

{
  "paymentId": 9011,
  "loanRef": "7204",
  "status": "POSTED",
  "attemptNumber": 1,
  "amount": "517.14",
  "currency": "USD",
  "rail": "ACH",
  "effectiveDate": "2026-09-12",
  "source": "BORROWER",
  "createdAt": "2026-09-11T17:03:00Z",
  "postedTransactionRef": "30411",
  "timeline": [
    { "occurredAt": "2026-09-11T17:03:00Z", "source": "LMS", "state": "SUBMITTED" },
    { "occurredAt": "2026-09-15T14:22:08Z", "source": "LMS", "state": "POSTED", "postedTransactionRef": "30411" }
  ]
}

The posting timestamp is September 15, but the ledger transaction is value-dated September 12. This prevents settlement latency from creating artificial delinquency or extra accrual. Allocation lives on the posted ledger transaction—read GET /v1/loans/7204/transactions/30411 for the principal, interest, and fee portions. There is no cancel or return call: returns arrive from the provider, and return-code policy decides retry, instrument invalidation, and any autopay reaction.

Download the receipt

GET/v1/loans/7204/payments/9011/receipt

curl "$BASE/v1/loans/7204/payments/9011/receipt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  --output harbor-payment-9011.pdf

The receipt is a PDF attachment available only for a POSTED payment—any other status fails validation. A later ACH return links back to the original payment as a new linked intent and can move the loan back into delinquency, but it does not alter the issued receipt or erase the timeline.