Payment integration
A payment provider can answer with HTTP 200 and still decline payment after payment. A request runs into a timeout, and nobody knows whether money moved. A webhook arrives twice, another one never. None of this shows up in a demo, all of it shows up in the first monthly statement. I build payment flows that expect these cases instead of discovering them.
Assessment and target design as a bounded engagement of two to three weeks, then implementation provider by provider. Existing payments keep running throughout.
Remote from Germany. Straight with me, no agency in between.
The starting point
Every provider has good documentation for the case where everything works. The code for it is written in a day. The real work lies in the cases in between: the request to the provider runs into a timeout, and your system does not know whether the card was charged. Retry blindly and you charge twice. Do not retry and you lose the payment. Both happen in real systems every day, just rarely enough that no test ever catches it.
The second part arrives at the end of the month. Your system counts one total, the provider's settlement another. In between sit payments stuck in an intermediate state, chargebacks, refunds and currency differences. Each of these cases is unremarkable on its own. Together they decide whether your finance team trusts your numbers.
The third part is dependency. Write a provider straight into the checkout and you have not integrated it, you have built it in. Then switching is a project, a second provider for a new market is a rebuild, and an outage at the provider is an outage of your own sales. In a payment backend for more than six million users, each of the nine providers therefore got a service of its own behind a shared interface. After that, a new provider was a matter of days rather than weeks.
Does any of this sound familiar?What I do
The rest of the system knows a payment operation, not a provider. Every provider becomes an adapter behind that interface, with its own data models, error codes and quirks. The peculiarities stay where they belong, and a second provider is one more adapter rather than a change across the whole application.
Every payment operation gets a key that identifies the business operation, not the individual attempt. A request can then be retried safely after a timeout: the second call returns the result of the first instead of moving money a second time. Whatever still fails lands in a queue of its own with an owner, not in limbo.
Providers deliver events at least once, not exactly once, and not necessarily in order. So processing verifies the signature, recognises repeats by the event, accepts first and processes afterwards, and fetches the state from the provider when an event fails to arrive. An order then no longer depends on a single HTTP request getting through.
A daily reconciliation between your own records and the provider's reports, with a list of discrepancies and a rule for each kind: intermediate state, chargeback, refund, currency difference. At the end of the month there is then no surprise left open, only a list of cases already resolved.
With payments, the technical error rate is not what counts. The business rate is: how many payments that were started actually arrive, per provider, payment method and country. A provider that answers 200 and declines twice as often as last week only shows up this way. The same metric makes it possible to route to a second provider during an outage.
Card data goes straight from the browser to the provider, through its form fields or payment page. Your servers only ever see a token. That keeps your own audit scope small and the architecture simple. Strong customer authentication runs through the provider's flows instead of being built in-house.
Do your numbers match at the end of the month?
Tell me which providers you use today and where it last went wrong. You get an assessment before you commission anything.
How it runs
Four steps, and after the second it is clear what changes and what it costs. No step commits you to the next.
Which providers, which payment methods, which markets. Where the provider sits in the code, how webhooks are processed today and what the last monthly reconciliations showed. Plus the cases that cost your support team the most work.
The internal payment interface, the idempotency rules, the webhook path and the reconciliation, as a short document with the effort for each step. That lets you decide, including against me.
One provider after another moves behind the new interface while existing payments keep flowing. Old system and new path run in parallel for a while, and for each data area it is decided upfront which system is right when they disagree.
The first complete monthly reconciliation through the new path, the metrics per provider and a runbook for the cases that happen at night. After that it belongs to your team.
The outcome
A timeout is a reason to retry, not a risk. Your support team stops issuing refunds for mistakes made by your own system.
At month end, finance gets a list of resolved cases instead of a difference somebody has to explain.
A second provider for a new market, or moving away from the first, is an adapter, not a rebuild. That also strengthens the next price negotiation.
Not whether the server is up, but how many payments get through, per provider. A creeping decline shows up the same day, not in the monthly report.
Technologies I use
From practice
A payment API built for a different order of magnitude. Nine providers behind a shared interface, each as a service of its own, idempotency per business operation and a reconciliation that adds up at month end. Rebuilt while payments kept running.
Read the case studyAlso from real projects
The same idea as behind the payment interface: a boundary where foreign data models are translated so that the rest of the system never sees them.
Read the article
Who you are talking to
I am Tim Rutte. More than 20 years in software development, four of them on a payment API with nine providers and more than six million users. You talk to the person who touches your code, from the first call to the handover.
Common questions
That depends less on technology than on your markets and payment methods. Stripe is quick to integrate and a good start for most products. Adyen tends to pay off with large volume and many countries. More important than the choice is that it stays reversible: with an internal payment interface, the second provider is an adapter, not a decision for the next ten years.
Usually not at the start. A second one pays off when a market demands a payment method the first cannot offer, or when a provider outage is so expensive that you need to be able to reroute. The architecture should allow both, even if you never use them.
First the internal interface is built, and the current provider becomes its first adapter. Then the new one joins as the second and takes over step by step, by country or payment method for example. Existing subscriptions and stored payment methods are the most demanding part, because they have to be migrated between providers. We clarify that with both providers upfront.
That the same call made twice has the same effect as made once. With payments it is the difference between a harmless retry and a double charge. The large providers support idempotency keys for this, but only if your own system reuses the same key for the same business operation. That is exactly what most integrations lack.
The architecture is meant to ensure that card data never touches your servers: it goes straight from the browser to the provider, and your system only sees a token. That keeps the audit scope small. Which evidence you need specifically is for your provider or your assessor to settle. This service is not legal or compliance advice.
It is billed by effort, with assessment and target design as a bounded engagement of two to three weeks. I give the order of magnitude in the first conversation, once it is clear how many providers, payment methods and markets there are and how deeply the current provider is embedded in the code. One provider in a new product is different work from moving away from one that everything has depended on for years.
If the standard product handles the payment itself and the reconciliation adds up, usually not. It becomes worth it as soon as payments from several systems come together, subscriptions are added, or finance regularly has to explain differences. Then the payment flow is a system of its own, even if nobody calls it that.
Other services
Backends for SaaS and platforms that hold under real load: Go and PHP 8, event-driven, with tenant isolation and recovery designed in.
Learn moreSaaS platforms that still hold at the tenth customer: a decided tenant model, billing with usage metering you can prove, and a list of what breaks first at ten times the volume.
Learn moreOnline shops for retailers whose standard shop fails at the integration: inventory management, point of sale and store stock in real time, in-store pickup, search and product recommendations.
Learn more