Payout Reversal

Operational Use Cases

• Failed ACH/RTGS payout: Reverse funds when the lender-originated payout was rejected downstream.
• Duplicate disbursement: Claw back the extra payout made in error.
• Internal adjustments: Move funds back to the lender when the borrower never received the payout.

Applies to both Fixed and Dynamic repayment schedule engines. If interest recalculation is enabled, Embarc regenerates schedules or reprocesses transactions so projections stay accurate.

Lifecycle Snapshot

flowchart TD
    A[Identify payout to reverse] --> B[Initiate reversal via Payments API]
    B --> C[Platform posts payout reversal transaction]
    C --> D[Schedule and delinquency updated]

API Playbook

1. Initiate the reversal via Payments API
   HTTP

   POST /v1/payments
   {
     "loanId": 512,
     "mode": "LOG",
    "paymentCommand": "payoutRefund",
     "valueDate": "12 Nov 2025",
     "amount": 400.00,
     "note": "ACH payout failed",
     "externalReference": "PR-2025-11-12-ACHFAIL",
     "metadata": {
       "interestRefundCalculation": true
     }
   }

   • Use mode=INITIATE if you need Embarc to trigger the outgoing wire/ACH, or LOG if the reversal already happened and you are mirroring it.
   • metadata.interestRefundCalculation mirrors the flag on the underlying loan command. Omitting it defaults to true.
   • Embarc posts the payout reversal loan transaction immediately after the payment call and refreshes amortization on both repayment engines when required.

Key validations

• Loan must be in a refundable status (Active, Overpaid, or Closed per policy).
• valueDate/transaction date cannot be in the future or before the previous monetary transaction.
• When interest recalculation is enabled, Embarc replays the schedule so statements remain accurate.

Tips for Operations Teams

• Use interestRefundCalculation=false (via metadata) if you need to reverse principal only.
• Document the processor reference in externalReference so finance can reconcile against payment rails.

Baseline Example (Fixed Loan A)

Assume a disbursement mistake sent USD 400 extra on day 1. Reversal steps:

Loan summary before refund

{
  "principalDisbursed": 12000.00,
  "principalOutstanding": 12000.00,
  "status": "Active"
}

Transactions created

Loan summary delta

Before refund (excerpt of installments #10–#12):

After refund (same dates, regenerated via the Fixed Schedule engine):

Baseline A uses the equal-installment regeneration strategy built into the Fixed Schedule engine. After a principal reduction, the EMI stays at USD 1,066.19 and the generator shortens the payoff by shrinking (or removing) the last installment. If your product uses a “reduce EMI” strategy, expect the EMI to fall instead—document the strategy your product applies so servicing teams know which outcome to expect.

Loan summary after refund

{
  "principalDisbursed": 11600.00,
  "principalOutstanding": 11600.00,
  "status": "Active"
}

Accounting snapshot

Verification checklist

1. GET /v1/loans/{id}?associations=transactions,loanSummary to confirm the new PAYOUT_REFUND entry and updated principal figures.
2. Verify the repayment schedule (or payoff template) reflects the lower principal.
3. Check your payment rail logs to ensure the reversal settled for USD 400 with the correct external reference.

Sandbox request template

POST /v1/payments
{
  "loanId": {{baselineFixedLoanId}},
  "mode": "LOG",
  "paymentCommand": "payoutRefund",
  "valueDate": "05 Jan 2026",
  "amount": 400.00,
  "note": "Duplicate disbursement fix",
  "externalReference": "PR-BL-A-0001",
  "metadata": {
    "interestRefundCalculation": false
  }
}