Loan lifecycle

Every endpoint is under /api/v1 and requires a partner API key (see Authentication). Reads need partner.loans.read; writes need partner.loans.write. Amounts are decimals in the loan's currency; enum fields are integers.

Create a loan

POST /api/v1/loans — originates a draft loan. The borrower is upserted by national id (so you don't track Loanly ids) and the product is resolved by code.

curl -X POST /api/v1/loans -H "Authorization: Bearer pat_…" -H "Content-Type: application/json" -d '{
  "nationalId": "1234567890",
  "borrowerName": "Anna Jónsdóttir",
  "productCode": "CASH",
  "principal": 300000,
  "numberOfInstallments": 12,
  "startDate": "2026-02-01",
  "firstDueDate": "2026-03-01",
  "email": "anna@example.com",
  "countryCode": "IS"
}'

{ "loanId": 1001, "reference": "A1B2C3D4", "status": 1,
  "amortizedPrincipal": 309000, "aprPercent": 15.0, "numberOfInstallments": 12 }

The loan is priced with the product's method, fees, and conventions — identical to a console origination. It starts in Draft; no money has moved yet.

Activate (confirm funding)

POST /api/v1/loans/{id}/activate — a partner funds the loan from its own system, then tells Loanly it's funded. Loanly moves no money here: it records an external disbursement (for audit), opens the ledger with the outstanding principal, and flips the loan to Active so servicing begins.

curl -X POST /api/v1/loans/1001/activate -H "Authorization: Bearer pat_…" -d '{
  "fundedReference": "PARTNER-TXN-42",
  "fundedAt": "2026-02-01"
}'

{ "loanId": 1001, "status": 4, "disbursedAmount": 300000, "outstandingPrincipal": 309000 }

note

The partner path never calls a bank rail — the partner's system already sent the money. Contrast the console, where Loanly disburses and settles the payout in the background. See Concepts → Disbursement.

Record a payment

POST /api/v1/loans/{id}/payments — applies an incoming payment through the waterfall. Supply an idempotencyKey to make retries safe.

curl -X POST /api/v1/loans/1001/payments -H "Authorization: Bearer pat_…" -d '{
  "amount": 27890,
  "valueDate": "2026-03-01",
  "source": 4,
  "idempotencyKey": "5f2c…"
}'

source is the payment channel: 1 BankClaim · 2 DirectDebit · 3 Card · 4 BankTransfer · 5 Manual.

Restructure and settle

Endpoint	Does
POST /api/v1/loans/{id}/prepay	Extra principal payment; re-amortizes the remaining schedule on the lower balance.
POST /api/v1/loans/{id}/reterm	Puts the loan on a new schedule — numberOfInstallments, firstDueDate, optional interestRatePercent.
POST /api/v1/loans/{id}/payup-quote	Returns the early-settlement figure as of a date — read-only, changes nothing.
POST /api/v1/loans/{id}/payup	Settles the loan early and closes it.

Read loans

Endpoint	Returns
GET /api/v1/loans?page=1&pageSize=20	A page of loan summaries (reference, national id, product code, status, outstanding).
GET /api/v1/loans/{id}	The partner view of one loan: header, current terms, schedule, and payments.

The partner loan view deliberately excludes the internal servicing surface — general-ledger journals, IFRS-9 provisions, disbursement attempts, and the audit trail stay on the admin API.