Advance Payment Refund

When to use it

• Accidental early autopay: A scheduled debit fired before the borrower expected and you need to return the extra installment while keeping the loan open.
• Operational corrections: Back-office staff posted a repayment to the wrong loan or duplicated it, but the customer wants the overpayment back immediately.
• Merchant or partner disputes: A merchant cancelled part of an order after funds were already collected from the borrower and you want to unwind just that portion.

Unlike a credit-balance refund (which requires the loan status = Overpaid), the advance payment refund works while the contract is still Active and only touches the paid-in-advance balance.

Preconditions checklist

1. Loan status = Active (not Closed/Overpaid/Fraud/etc.).
2. At least one repayment already posted (loanSummary.totalRepayment > 0).
3. paidInAdvance.paidInAdvance > 0 (visible on GET /v1/loans/{loanId}?associations=paidInAdvance).
4. Refund date must be today or earlier (but not before the last repayment or charge-off date).
5. Amount ≤ the paid-in-advance balance returned by the template endpoint.

If any requirement fails, the command returns HTTP 400 with a descriptive validation error—surface those codes to agents so they can guide the borrower.

Lifecycle snapshot

flowchart TD
    A[Identify paid-in-advance amount] --> B[Send refund via Payments API]
    B --> C[Submit refundByCash command]
    C --> D[Loan reprocesses allocation and interest]
    D --> E{Need to undo?}
    E -->|Yes| F[Reverse the refundByCash transaction]
    E -->|No| G[Loan stays active with paid-in-advance cleared]

Embarc best practice: always initiate the outward payment via the Payments API (so accounting and gateway logs stay consistent), then call the loan transaction to mirror the movement in the schedule.

Baseline Example (Fixed Loan A)

Scenario: Baseline A borrower set up autopay for installment #2 (due 13 Feb 2026). The ACH pull executed early on 31 Jan 2026, so by 01 Feb the loan shows:

"paidInAdvance": { "paidInAdvance": 1066.19 },
"loanSummary": {
  "status": { "code": "loanStatusType.active" },
  "totalPaidInAdvance": 1066.19,
  "totalRefunds": 0.00
},
"transactions": [
  { "type": { "code": "loanTransactionType.disbursement" }, "amount": 12000.00 },
  { "type": { "code": "loanTransactionType.repayment" }, "date": [2026,1,13], "amount": 1066.19 },
  { "type": { "code": "loanTransactionType.repayment" }, "date": [2026,1,31], "amount": 1066.19 }
]

Operations decides to return that early installment.

API call

POST /v1/loans/41/transactions?command=refundByCash
{
  "locale": "en",
  "dateFormat": "dd MMM yyyy",
  "transactionDate": "01 Feb 2026",
  "transactionAmount": 1066.19,
  "paymentTypeId": 1,
  "note": "Refund early autopay for installment #2",
  "externalId": "ALR-BL-A-0001"
}

After the command

"paidInAdvance": { "paidInAdvance": 0.00 },
"loanSummary": {
  "totalPaidInAdvance": 0.00,
  "totalRefunds": 1066.19,
  "principalOutstanding": 10106.81,
  "status": { "code": "loanStatusType.active" }
},
"transactions": [
  ...,
  {
    "type": { "code": "loanTransactionType.refundForActiveLoans" },
    "amount": 1066.19,
    "date": [2026,2,1],
    "paymentDetailData": { "paymentType": { "name": "ACH" } },
    "note": "Refund early autopay for installment #2"
  }
]

Key observations:

• Installment #2 reopens (it will now fall due again on 13 Feb 2026).
• totalRefunds captures the aggregate amount for reporting.
• Because the loan remains Active, autopay resumes as normal for future cycles.

Accounting snapshot

No interest or fee reclassification is needed; the transaction simply reverses the components that had been paid ahead.

Verification checklist

1. GET /loans/{id}?associations=transactions,paidInAdvance,loanSummary → confirm paidInAdvance = 0 and a refundForActiveLoans transaction exists.
2. Check the Payments system to verify the outward ACH/Wire succeeded (Embarc customers should drive this via /payments).
3. If autopay pulled the amount again later, the paid-in-advance bucket will refill automatically—agents can repeat the refund if policy allows.
4. To reverse the refund, call POST /loans/{id}/transactions/{txnId}?command=undo before any later user transactions occur.

Operational tips

1. Surface paid-in-advance in UI: Show the value from the loan resource so agents immediately know how much can be refunded.
2. Pair with notes/external IDs: Use descriptive text ("Refund early autopay for installment #2") and an external case ID so auditors can trace the justification.
3. Communicate to autopay teams: If the refund address a recurring configuration issue (e.g., autopay schedule misaligned), pause or adjust the autopay enrollment to avoid repeated refunds.
4. Reporting: Filter transactions where type.code = loanTransactionType.refundForActiveLoans to quantify active-loan refunds per product, merchant, or agent.

Following this workflow keeps customer experience smooth: cash is returned, the loan schedule stays accurate, and compliance teams get clear audit data.