Paying out to debit cards in minutes.
Push-to-card payouts on a regulated banking platform, built so every payout either lands on the card or goes back to the account it came from. Results delivered by our principal in regulated production before Aripone was formed.
- Client
- A regulated banking platform for US organizations
- Team
- Our principal, Rey Narvaez, as technical lead for the API integrations
- Outcome
- Payouts in minutes, not one to three business days
- Date
- 2023 to 2024
Rails: Visa Direct and Mastercard MoneySend through a card processor, with balances held at a banking-as-a-service provider and bank accounts linked through a third.
The problem
The platform held deposit accounts for US organizations such as clubs, associations and nonprofits, and let them pay their members and vendors. Payouts went by ACH and took one to three business days. The organizations wanted to pay someone back the same day, to the debit card already in their wallet.
A card payout touches two providers. The money sits in an account at the banking provider, and the card processor sends it over Visa Direct or Mastercard MoneySend. Either call can time out, and both report back by webhook: late, twice or not at all. A payout that left the account but never reached the card, or reached it twice, is money the platform owes someone.
The fix
- Every payout became a record with fixed states, saved before any provider call: requested, funds held, sent, then paid or returned.
- The card was checked for payout eligibility first, so most declines happened before any money moved.
- Funds were held next, with a book payment from the organization's account into a payout holding account. The card payout went out only after the hold succeeded.
- Both providers received the same idempotency key, built from the payout ID, so a retry after a crash could not create a second hold or a second payout.
- A timeout counted as unknown, not failed. The payout was looked up by its reference before anything was retried.
- Webhooks from both providers were verified against their signatures, and each event ID was stored under a unique constraint, so a duplicate was acknowledged and ignored.
- A declined or returned payout moved the money back to the organization's account with a reversing book payment.
- A daily job compared the platform's ledger, the holding account and the processor's payout report. Any difference went to a queue with an owner.
| Step | Money | If it fails |
|---|---|---|
| Check the card | Not moved yet | Declined up front, nothing to undo |
| Hold the funds | Organization account to holding account | Retried with the same key |
| Send the payout | Holding account to the card | Looked up by reference before any retry |
| Settle | Paid, or returned to the organization | Caught by the next daily reconciliation |
The outcome
Payouts reached the card in minutes instead of one to three business days. Every payout ended in one of two states: paid, or the money back in the organization's account. No payout was sent twice, and none was left stuck between the two providers.
The same rules (an idempotency key on every money write, verified webhooks and an event-ID table) became the standard for every integration on the platform, bank linking and identity included. A rules engine classified each payout, hold and reversal, so organizations saw them in their books under the right category.
Your payouts
Find where your money can fail halfway.
The Payment Operations Assessment is one or two weeks at a fixed fee, published on the pricing page. We trace every path that creates, moves or refunds money, test what happens when a provider times out or answers twice, and check whether your ledger, provider and bank agree. You get a severity-ranked findings report, a target design, a costed roadmap and a fixed-price quote for the build.