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.

  • Laravel
  • PHP
  • Payliance
  • NPS
  • ACH
  • Debit cards
  • MySQL
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

diagram · Lifecycle of a debit
  1. 01ScheduledA payment is due on the loan.
  2. 02SubmittedThe debit goes out on ACH or debit card rails.
  3. 03Pending settlementAccepted and waiting for the bank.
  4. 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.