Credit Balance Refund

Operational Use Cases

• Overpayment return: Borrower sends more than the outstanding balance (duplicate ACH, manual transfer) and expects the surplus back.
• Standing-instruction cleanup: Auto-debit keeps running after closure; use this command to return the extra cash and move the loan from Overpaid → Active (or Closed if zero balance remains).

Works for both Fixed Schedule and Dynamic Schedule loans because it only touches loan transactions, not the repayment schedule.

Lifecycle Snapshot

flowchart TD
    A[Loan status is Overpaid] --> B[Submit credit balance refund command]
    B --> C[Credit balance refund transaction posted]
    C --> D{Credit still remaining?}
    D -->|Yes| E[Loan stays Overpaid]
    D -->|No| F[Loan returns to Active or Closed]

API Playbook

1. Confirm the balance

   HTTP

   GET /v1/loans/{loanId}?associations=loanSummary

   Ensure loanSummary.status = Overpaid and note totalOverpaid.

2. Post the refund

   HTTP

   POST /v1/loans/{loanId}/transactions?command=creditBalanceRefund
   {
     "transactionDate": "18 Feb 2026",
     "transactionAmount": 25.00,
     "paymentTypeId": 2,
     "note": "Return duplicate ACH",
     "externalId": "CBR-2026-02-18-001",
     "locale": "en",
     "dateFormat": "dd MMM yyyy"
   }

3. Verify

   • Check loanSummary.totalOverpaid drops by the refunded amount.
   • Confirm a CREDIT_BALANCE_REFUND transaction exists with your payment metadata.
   • If totalOverpaid hits zero, the loan status automatically reverts to Active (or stays Closed if the principal balance is already zero).

Baseline Example (Fixed Loan A)

Baseline A has USD 50.00 more than required after the borrower prepays the final installment. Operations need to return USD 30.00 and leave USD 20.00 on the account for future adjustments.

Transactions created

Loan summary delta

If you repeat the command for the remaining USD 20.00, the loan transitions to Active (or Closed if no principal remains) because the credit balance is cleared.

Tips for Operations Teams

1. Always coordinate with payouts: the API records the refund, but you still need to send money through your payments rail (ACH, wire, etc.).
2. Use externalId to tie the refund to your payout batch for audit and idempotency.
3. Run Close of Business after high-volume refunds so GL/export files reflect the reduced receivable balance.
4. Don’t use this command for merchant/lender-driven reversals—that’s what merchantIssuedRefund and payoutRefund are for.

Following this sequence keeps credit balances under control while preserving clean audit and accounting records.