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.

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

The posted refund transaction is what the funding pays out against; no other process can consume the same credit twice.

Post the ledger effect

A human call carries LendEasy-Case naming an open case when case management is enabled; without it the call is rejected before execution.

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, and maker-checker can park the command for a second approver.

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 and must be approved by a different user before submission. It moves money for the ledger effect the command created—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 closure waits until the cash is settled or otherwise disposed. 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 the funding 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.

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—joined through the case.