Issue a cash refund

A cash refund moves money out. It requires both a ledger basis—why the amount is owed—and a verified payout path. The two are deliberately separate operations: the governed command posts the ledger effect, and a REFUND funding moves the money.

Refund sources

Permitted sources include an approved account credit, overcollection, settlement correction, or charge-refund excess. The basis lives in the case—evidence, approval, and the customer conversation—because the command itself cannot create refundable value from a note.

Post the ledger effect

The refund is the governed native command refundByCash. A human call carries LendEasy-Case naming an open case when case management is enabled; without it the call is rejected before execution.

curl -X POST "$BASE/v1/loans/7204/transactions?command=refundByCash" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "LendEasy-Case: case_HBR_REFUND_9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hbr-cash-refund-2027-06-05" \
  -d '{
    "transactionDate": "2027-06-05",
    "transactionAmount": 63.20,
    "note": "Verified overpayment refund.",
    "dateFormat": "yyyy-MM-dd",
    "locale": "en"
  }'

{
  "officeId": 1,
  "clientId": 412,
  "loanId": 7204,
  "resourceId": 30441,
  "changes": {
    "transactionDate": "2027-06-05",
    "transactionAmount": 63.20
  }
}

Refund commands also accept native payment-detail fields when the tenant records how the money will move. The execution writes a governance record, and maker-checker can park the command for a second approver.

Move the money

Outbound cash rides a refund funding, which has its own second-person control:

curl -X POST "$BASE/v1/loans/7204/fundings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "LendEasy-Case: case_HBR_REFUND_9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hbr-cash-refund-funding-2027-06-05" \
  -d '{
    "amount": "63.20",
    "currency": "USD",
    "fundingType": "REFUND",
    "recipientType": "BORROWER",
    "recipientRef": "412",
    "instrumentId": 704,
    "rail": "ACH",
    "reason": "Verified overpayment refund per case."
  }'

The funding starts in APPROVAL_REQUIRED; a different user must approve it before submission, and it settles through SUBMITTED → PROCESSING → SETTLED_PENDING_POST → POSTED. The funding moves money for the ledger effect the command created—it does not post a second ledger transaction.

Recipient controls

The selected instrument must belong to the entitled recipient and be active and verified; DISBURSEMENT_HOLD restrictions block funding creation. Changing the destination means cancelling the funding before submission and creating a new one—nothing is redirected in flight. Masked destination details appear in review; raw account data does not.

Failure handling

A failed payout does not automatically create another payout. Retry with a new funding linked to the same case, and only after the provider outcome is definitive. If cash settled but ledger posting failed, the funding lands in POSTED_FAILED_REVIEW and the posting is repaired—money is never sent twice on uncertainty.

Evidence

The completed refund links across the ledger transaction, governance record, funding approval and settlement, instrument mask, customer notice, and reconciliation result—each readable from its own API, all joined through the case.