All case studies
02 · fintech · payments
ACH and debit card payments: settlement, returns and retries
Debits move from submission to settlement through explicit states, with safe retries and a clear path to collections.
- Client
- Stepping Stone Loans, a US consumer lender
- Role
- Senior full-stack & AI engineer
- Period
- Dec 2024 – present
- Engagement
- Long-term contract through Upwork
Problem
Debits on ACH and debit card rails, through the Payliance and NPS payment processors, fail in many ways (R01 insufficient funds, closed, stopped or frozen accounts), and each failure needs a different, auditable next step.
How it works
- 01ScheduledA payment is due on the loan.
- 02SubmittedThe debit goes out on ACH or debit card rails.
- 03Pending settlementAccepted and waiting for the bank.
- 04SettledMoney arrived; the loan is updated.
When a debit fails
- ReturnedReturn codes such as R01 (insufficient funds) map to a defined next step.
- RetryRescheduled only when the retry checks pass.
- No retryWait, ask the borrower to pick a date, or hand off to collections.
- Written offAdmins are warned, then automatic debits stop.
What I built
- Designed explicit states for each debit, from submission to settlement.
- Mapped return codes (R01 NSF, account closed, stopped, frozen) to specific next steps.
- Built card collection with partial and split payments within a fixed attempt cap.
- Added write-off rules that warn admins, then stop automatic debits on written-off loans.
Key decisions
- One known state per debit
- Each debit is always in exactly one state, so every failure gets a defined, auditable next step instead of a judgment call.
- Split card payments within a fixed cap
- Card collection accepts partial and split payments, and a fixed attempt cap keeps a card from being retried without limit.
Guardrails
- A retry is scheduled only when balance, retry-window and attempt-limit checks pass.
Result
Returned debits follow defined rules, retries stay within their limits, and written-off loans stop being debited automatically.
media note
The lender’s internal systems are private, so this case study uses words and a diagram instead of screenshots.