Declined Payments: Open-Sourcing an Agentic Payment Waterfalling Tool

Here's a stat most people never think about: 10 percent of abandoned checkouts happen simply because the card gets declined.

We think a lot about cascading payments on API-inaccessible websites and acquirers at Soap Payments. Historically, you could not waterfall payments unless there was an API for it. Now with browser agents, that changes.

See live demo here.

We are open-sourcing a POC of an agentic tool that combines API-based with UI-based payments waterfalling.

What is payment waterfalling?

Payment waterfalling, also called payment cascading, means retrying a declined payment through another route instead of giving up. If the first processor or acquirer declines a card, the payment falls through to the next one in line, like water down a series of steps, until one approves it or every option is used.

The customer sees one checkout and, ideally, one successful payment. The merchant keeps a sale that would otherwise have been abandoned.

Why cards get declined: soft vs hard declines

Not every decline means the customer can't pay. A hard decline is final: a closed account, a card reported stolen, an invalid number. Retrying it anywhere is pointless and can count against the merchant. A soft decline is temporary or specific to one route: the issuer's risk system didn't like that acquirer, a processor timed out, or the merchant category triggered a rule. Soft declines are where waterfalling recovers revenue.

API-based vs UI-based waterfalling

Traditional waterfalling only works where every route has an API: the payment orchestration layer sends the card to processor A, reads the decline, and sends it to processor B. Many payment routes have no API at all, only a website with a checkout form, so they were left out.

Browser agents change that. An AI agent can drive a real browser, fill in a payment form and read the result, the way a person would. That turns a website into one more step in the waterfall. Our proof of concept combines both: API calls where an API exists, and a browser agent where it doesn't.

How the open-source POC is built

Built with Stagehand as agent harness, Browserbase for remote headless browsers, Basis Theory for sandboxed card tokenization and sandbox payments APIs from Checkout.com, Stripe, and Adyen.

• Stagehand is the agent harness that drives the browser.
• Browserbase runs the headless browsers remotely.
• Basis Theory tokenizes the card in a sandbox, so the agent never handles raw card numbers.
• Checkout.com, Stripe and Adyen sandbox APIs are the API-based steps of the waterfall.

Guardrails for retrying declined payments

Waterfalling done carelessly creates new problems, so any production version needs rules:

• Retry soft declines only, never hard declines.
• Respect the card networks' limits on retrying a declined card, which can carry fees.
• Never charge the customer twice: one purchase, at most one approved payment.
• Keep card data tokenized, so neither agents nor logs see raw card numbers.

The future of commerce is changing fast and we are very excited to see what others are building in the space. For more on how we use agents in payments, read Need for Speed in Agentic Finance.

OSS link: github.com/filip-michalsky/agentic-waterfall-poc

Frequently asked questions

What is payment waterfalling?

Retrying a declined payment through another processor or acquirer, in order, until one approves it. It is also called payment cascading.

How many checkouts are abandoned because of declined cards?

About 10 percent of abandoned checkouts happen simply because the card gets declined.

Can you waterfall payments without an API?

Historically, no. With browser agents, a website's checkout form can become a step in the waterfall, which is what this proof of concept shows.

Is the tool open source?

Yes. The proof of concept is on GitHub at github.com/filip-michalsky/agentic-waterfall-poc, with a live demo linked above.