Merchant Credit

Operational Use Cases

Order cancellations/returns: Merchant refunds the borrower, so the loan balance must decrease accordingly.
Partner-funded price adjustments: Merchant partially refunds to honor price guarantees.
Dispute resolutions: Merchant credits the borrower and informs the lender to mirror the adjustment.

Applies to both Fixed and Dynamic repayment schedule engines. Interest recalculation behaves the same as payout reversals.

Lifecycle Snapshot

flowchart LR
    A[Receive merchant credit confirmation] --> B[Log credit via Payments API]
    B --> C[Loan posts merchant credit transaction]
    C --> D[Interest portion auto-created when requested]

API Playbook

Log the merchant credit via Payments API
```
POST /v1/payments
{
  "loanId": 512,
  "mode": "LOG",
  "paymentCommand": "merchantIssuedRefund",
  "valueDate": "14 Nov 2025",
  "amount": 75.00,
  "note": "Return of SKU 123",
  "externalReference": "MR-2025-11-14-SKU123",
  "metadata": {
    "interestRefundCalculation": false
  }
}
```
- Use mode=INITIATE if Embarc should push funds to the borrower on the merchant’s behalf.
- metadata.interestRefundCalculation determines whether Embarc should auto-create an interest refund.
- Once the payment call finishes, Embarc records the loan transaction and recalculates amortization if needed.

Key validations

Loan must be Active/Refundable and valueDate cannot precede prior repayments.
Interest recalculation replays automatically when the refund is not the latest transaction.

Tips for Operations Teams

If the merchant credit includes both principal and interest, leave interestRefundCalculation as true (or omit it) so Embarc calculates the interest portion automatically.

Baseline Example (Dynamic Loan B)

Merchant issues a USD 75.00 credit for installment #3 on 14 Feb 2026.

Transactions created

Date	Type	Total Amount	Allocation (Principal / Interest)	Notes
14 Feb 2026	MERCHANT_ISSUED_REFUND	75.00	75.00 / 0.00 (`interestRefundCalculation=false`)	Credit logged via Payments API (`mode=LOG`).
14 Feb 2026	INTEREST_REFUND (optional)	2.77	0.00 / 2.77 (`interestRefundCalculation=true`)	Auto-created when metadata flag is true and installment interest must be returned.

Loan summary delta

Metric	Principal-only refund	Principal + interest refund
Principal outstanding	300.00 → 225.00	300.00 → 225.00
Interest outstanding	unchanged	2.77 → 0.00 (installment #4 interest cleared)

Loan summary delta

Metric	Before	After
Principal outstanding	USD 300.00	USD 225.00
Schedule	Installment #3 marked paid, future installments unchanged	—

Accounting snapshot

Entry	Debit	Credit	Amount
Refund settlement	Loans Receivable (`112601`)	Merchant Refund Clearing (`213500`)	USD 75.00
(if interest refund)	Interest Income (`404000`)	Merchant Refund Clearing (`213500`)	USD 2.77

Even though the lender did not move cash, the ledger still credits the merchant clearing liability because the borrower’s balance dropped. Embarc treats the command as a merchant-funded credit, so the receivable decreases while a liability is recorded until the merchant settles with the lender.

Verification checklist

GET /v1/loans/{id}?associations=transactions,loanSummary to verify the MERCHANT_ISSUED_REFUND transaction and lower outstanding principal.
Confirm the Payments API request references the merchant credit ID for reconciliation.
If interestRefundCalculation=true, ensure the additional INTEREST_REFUND transaction exists and the schedule reflects the interest reversal.

Sandbox request template

POST /v1/payments
{
  "loanId": {{baselineDynamicLoanId}},
  "mode": "LOG",
  "paymentCommand": "merchantIssuedRefund",
  "valueDate": "14 Feb 2026",
  "amount": 75.00,
  "note": "Return of SKU 123",
  "externalReference": "MR-BL-B-0001",
  "metadata": {
    "interestRefundCalculation": false
  }
}