Down Payment

Operational Use Cases

• Point-of-sale deposits: BNPL or installment plans that require the borrower to pay a percentage immediately when the order is disbursed.
• Merchant-funded contributions: Merchant pays part of the ticket up front while the lender finances the remainder; the down payment records that cash movement explicitly.
• Auto-sweeps at disbursement: Enable automatic collection on disbursement so the borrower’s default payment method is charged without agent intervention, with manual capture as the fallback.

Only Dynamic Schedule products can enable down payments (enableDownPayment). The configuration adds three key fields to the product/loan:

Lifecycle Snapshot

flowchart TD
    A[Disbursement posted] --> B{Down payment enabled?}
    B -->|No| C[Standard amortization]
    B -->|Yes| D[Calculate down payment amount]
    D --> E{Auto-repayment flag enabled?}
    E -->|Yes| F[Auto sweep posts DOWN_PAYMENT transaction]
    E -->|No| G[Schedule shows DP period awaiting manual payment]
    F --> H[Loan status updated]
    G --> I[Operations posts manual down payment]
    I --> H

Key differences vs. regular repayments:

• The schedule always shows a dedicated DP period separate from installment #1.
• Statements and delinquency calculations treat down payments as their own bucket, so missing the DP period will mark the loan delinquent even before installment #1 is due.
• Down payments can be reversed with the standard chargeback command, so dispute handling is identical to repayments.

API Playbook

1. Confirm product settings

   HTTP

   GET /v1/loanproducts/{productId}

   Ensure enableDownPayment=true and the percentage matches the commercial offer.

2. Approve & disburse the loan

   • When the loan is disbursed, Embarc automatically posts the DP transaction if enableAutoRepaymentForDownPayment=true. The response from POST /loans/{loanId}?command=disburse includes the down-payment transaction ID in subResourceId.
   • If auto repayment is off (or fails), the schedule still shows the DP period but no transaction is posted yet.

3. Collect (or re-collect) the down payment

   HTTP

   POST /v1/loans/{loanId}/transactions?command=downPayment
   {
     "transactionDate": "05 Jan 2026",
     "transactionAmount": 200.00,
     "paymentTypeId": 2,
     "note": "Deposit collected at store",
     "externalId": "DP-INV-4589",
     "locale": "en",
     "dateFormat": "dd MMM yyyy"
   }

4. Adjust / reverse if needed

   • Use chargeback (command=chargeback) to reverse a down payment after a dispute.
   • Use adjustloantransaction if you need to edit the amount/metadata while keeping the transaction.

Baseline Example (Baseline D)

Baseline D (see baseline-loans.md) finances USD 800 with a 25% down payment. Auto-collection succeeds on 05 Jan 2026, so the balance immediately drops to USD 600 and the first installment isn’t due until 19 Jan 2026.

If auto-collection had failed, operations would call the manual API to post the down payment later; the schedule would continue to show the DP period as overdue until that transaction lands.

Loan summary delta

Accounting snapshot

Because it is a repayment-type transaction, no special GL mapping is required beyond the usual repayment accounts.

Verification Checklist

1. GET /v1/loans/{loanId}?associations=repaymentSchedule,transactions,loanSummary – confirm:
   • A DP period exists in the repayment schedule.
   • transactions[] contains an entry labeled DOWN_PAYMENT.
   • loanSummary.totalDownPayment (if exposed) or principalOutstanding reflects the reduced balance.
2. If auto-repayment should have fired but didn’t, review your payment automation logs or simply post the manual API call.
3. Chargeback a DP transaction in QA to confirm disputes follow the same workflow as repayments.
4. For UI design, clearly label the DP amount separate from installment #1 so borrowers know they’ve already paid part of the loan.

With these steps, servicing teams can explain exactly how and when down payments occur, troubleshoot autopay failures, and handle manual corrections using the same APIs they already know for repayments.