Payments API¶

Process, allocate, reverse, and refund loan payments. Supports recurring payments and payment previews.

Base permission: IsViewerOrAbove (read), IsLoanOfficerOrAbove (write)

Endpoints¶

Payments¶

Method	Path	Description	Permission
`GET`	`/payments`	List all payments	`IsViewerOrAbove`
`GET`	`/payments/{id}`	Get payment	`IsViewerOrAbove`
`GET`	`/loans/{id}/payments`	List loan's payments	`IsViewerOrAbove`
`POST`	`/loans/{id}/payments`	Record payment	`IsLoanOfficerOrAbove`

Record Payment¶

POST /api/v1/loans/{loan_id}/payments

{
  "amount": "500.00",
  "payment_method": "ach",
  "payment_instrument_id": "772a0622-a4bd-63f6-c938-668877662222",
  "effective_date": "2026-01-15",
  "external_id": "PMT-EXT-001"
}

Response (201):

{
  "id": "883b1733-b5ce-74g7-d049-779988773333",
  "loan_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "500.00",
  "payment_method": "ach",
  "status": "completed",
  "effective_date": "2026-01-15",
  "principal_applied": "412.50",
  "interest_applied": "62.50",
  "fees_applied": "25.00",
  "created_at": "2026-01-15T14:30:00Z"
}

Payment allocation follows the lending program's payment_allocation_order (typically: fees, interest, principal).

Preview Payment¶

Dry-run payment allocation without recording the payment.

POST /api/v1/loans/{loan_id}/payments/preview

{
  "amount": "500.00"
}

Response (200):

{
  "amount": "500.00",
  "principal_applied": "412.50",
  "interest_applied": "62.50",
  "fees_applied": "25.00",
  "remaining_principal": "8087.50",
  "overpayment": "0.00"
}

Business Actions¶

Reverse Payment¶

Creates a reversing entry and re-accrues interest. Optionally assesses an NSF fee.

POST /api/v1/payments/{id}/reverse

{
  "reason": "nsf",
  "assess_nsf_fee": true
}

Preconditions: Payment must be in completed status.

Effects:

Creates reversing GL journal entries
Re-accrues interest from the payment's effective date
Optionally assesses an NSF fee per fee schedule
Recalculates delinquency

Refund Payment¶

POST /api/v1/payments/{id}/refund

{
  "amount": "500.00",
  "reason": "Customer overpayment"
}

Backdate Payment¶

Change the effective date of a payment and reprocess allocation.

POST /api/v1/payments/{id}/backdate

{
  "effective_date": "2026-01-10"
}

Record Reimbursement¶

Record a reimbursement to the borrower (not a payment allocation).

POST /api/v1/loans/{loan_id}/payments/reimbursement

{
  "amount": "100.00",
  "reason": "Fee waiver reimbursement"
}

Recurring Payments¶

Method	Path	Description
`GET`	`/loans/{id}/recurring-payments`	List recurring payments
`POST`	`/loans/{id}/recurring-payments`	Create recurring payment
`POST`	`/recurring-payments/{id}/cancel`	Cancel recurring payment

Create Recurring Payment¶

POST /api/v1/loans/{loan_id}/recurring-payments

{
  "payment_instrument_id": "772a0622-a4bd-63f6-c938-668877662222",
  "amount": "312.50",
  "frequency": "monthly",
  "start_date": "2026-02-01",
  "end_date": null
}

Payment Methods¶

Value	Description
`ach`	ACH bank transfer
`wire`	Wire transfer
`check`	Check payment
`card`	Credit/debit card
`cash`	Cash payment
`other`	Other method