Refund a credit balance

A credit balance is money owed to the customer or another entitled party after overpayment, reversal, charge refund, merchant refund, or correction. Refunding it is two explicit operations: the governed command consumes the credit on the ledger, and a REFUND funding moves the cash.

On screen. Credit Balance Refund, in the Payments & credits column of the loan actions menu.

Consuming a credit, then paying it

CommandPOST /v1/loans/{loanId}/transactions?command=creditBalanceRefund

Case contextRequired on human calls

ApprovalMaker-checker; the funding needs a different user

Ledger effectThe credit is consumed by one refund transaction

UndoNone — cancel the funding, then correct in the case

A credit becomes cash

1. Credit existsautomatic
2. Refund postsconsumes the credit, no cash yetautomatic
3. Funding approvednot its creatora person
4. Cash settlesclosure waits for thiswaits

Harbor example

Harbor has a $63.20 posted credit after payoff reconciliation.

Stage	Credit on ledger	Cash settled
Before the command	$63.20	$0.00
creditBalanceRefund posted	$0.00 — consumed by the refund transaction	$0.00
Funding approved and submitted	$0.00	$0.00
Funding POSTED	$0.00	$63.20

Post the ledger effect

curl -X POST "$BASE/v1/loans/7204/transactions?command=creditBalanceRefund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "LendEasy-Case: case_HBR_PAYOFF_6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hbr-cbr-2028-02-20" \
  -d '{
    "transactionDate": "2028-02-20",
    "transactionAmount": 63.20,
    "note": "Post-payoff credit refund.",
    "dateFormat": "yyyy-MM-dd",
    "locale": "en"
  }'

{
  "officeId": 1,
  "clientId": 412,
  "loanId": 7204,
  "resourceId": 30455,
  "changes": {
    "transactionDate": "2028-02-20",
    "transactionAmount": 63.20
  }
}

The amount cannot exceed the loan’s current credit balance—read the loan summary first. Every execution writes a governance record.

Move the money

curl -X POST "$BASE/v1/loans/7204/fundings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "LendEasy-Case: case_HBR_PAYOFF_6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hbr-cbr-funding-2028-02-20" \
  -d '{
    "amount": "63.20",
    "currency": "USD",
    "fundingType": "REFUND",
    "recipientType": "BORROWER",
    "recipientRef": "412",
    "instrumentId": 704,
    "rail": "ACH",
    "reason": "Credit balance refund per case."
  }'

The funding starts in APPROVAL_REQUIRED; no second ledger transaction posts. DISBURSEMENT_HOLD restrictions block funding creation, and the instrument must belong to the entitled recipient and be active and verified. A credit on one customer’s loan cannot be paid to another party without explicit entitlement evidence and approval in the case.

Loan closure

The loan may reach a zero-obligation state while the refund funding is in flight, but the close command is rejected while the refund is unresolved—the credit is never rounded away or hidden.

Payout failure

On a definitive pre-settlement failure, the funding fails without touching the ledger refund; recreate it after review. If cash settled but posting failed, the funding lands in POSTED_FAILED_REVIEW and the posting is repaired—cash is never sent twice.

Partial refund and residual cents

Policy can permit a partial refund; the residual remains a visible credit with its own disposition. Amounts are exact—an internal sub-cent difference is a reconciliation exception, not a silent adjustment.

The case is what joins the evidence

Completion links the credit’s origins, the refund transaction, the governance record, the funding approval and settlement, the destination mask, the customer notice, and the reconciliation result — all joined through the case.

The refund transaction is never edited

A wrong amount or a wrong recipient is settled in the case: cancel the funding before submission, and post the correction as its own governed action. Any further money movement rides its own approved funding.