Implement Checkout.com in a legacy e-commerce without interrupting the service

This week we have completed the implementation of Checkout.com in the e-commerce of one of our clients. The result has been optimal: zero service interruptions and a single minor incident during the launch, resolved swiftly and without significant impact for users.

Stated this way, it might seem like just another integration of a new payment gateway. The reality was much more complex.

The challenge was not so much in connecting Checkout.com as it was in doing so on a platform with more than ten years of evolution, highly customized, with a considerable amount of legacy code and practically no technical documentation on many of the decisions accumulated over all those years.

Moreover, the implementation had to work in five different markets (three currently active and two others in preparation), with different payment methods, mobile applications, recurring payments, and pre-existing systems that had to continue coexisting with the new platform.

In such a scenario, integrating an API is only a small part of the project.

The problem was not installing a payment gateway

In a new project, incorporating a provider like Checkout.com can be a relatively contained process. There are SDKs, documentation, reference integrations, and even plugins for many platforms.

Here, none of those conveniences solved the problem.

The platform has been evolving for over a decade and contains a significant layer of customization built around the actual business processes.

Payments are not an isolated piece. They intervene in the creation and confirmation of orders, subscriptions, returns, mobile applications, Customer Service operations, and numerous internal processes.

That’s why replacing the payment infrastructure was not simply a matter of swapping one API call for another.

First, it was necessary to understand what the system actually did.

And in legacy software, there is often a significant difference between how an application is supposed to work and how it works after ten years of evolution.

Five markets and multiple payment methods

To the technological complexity was added the internationalization.

The platform currently operates in three countries and is preparing for two more markets. Each presents different requirements and payment methods.

Checkout.com had to incorporate:

• payments with Visa and Mastercard;
• Bizum in Spain;
• Apple Pay;
• Google Pay.

But those methods did not completely replace the previous ecosystem.

They had to coexist with:

• American Express, which continues to be processed through Redsys;
• Klarna;
• PayPal;
• bank transfer.

The result is much more akin to a payment matrix than to a single gateway:

market × payment method × device × order status × provider behavior.

Each combination can present distinct particularities.

And each particularity must work not only in the ideal case but also when a bank rejects a transaction, a user abandons a flow, an authentication fails, or a confirmation arrives asynchronously.

Migrating from Redsys without breaking what already worked

Another particularly delicate element was the coexistence with Redsys.

A payment migration rarely allows treating the previous system as if it ceased to exist overnight. There are data, historical behaviors, and functionalities built around it that must continue to work during the transition.

In our case, there was also a particularly sensitive requirement: recurring payments. The platform has clients with subscriptions and, therefore, tokenized cards used later for charges.

Changing the payment provider requires resolving what happens with those credentials and with the clients whose cards are not yet ready to operate with the new system.

For this, in addition to migrating the pre-existing tokens, we have also developed a mechanism that allows renewing pending tokenization cards through a €0 operation.

The system identifies in advance the cards that need to be updated and automatically notifies the client before the next charge is due.

This way, we ensure that a good portion of those cards are updated before the next charge, instead of discovering the problem when a renewal has already failed.

Anticipating is more important than reacting

One of the keys to success has been the support of the Account Manager from Checkout.com.

His role has gone far beyond answering specific queries. He has helped us anticipate possible problems, coordinate the necessary checks, and keep the validation roadmap updated until the launch moment.

In projects that affect such a critical process as payment, this collaboration between provider and technical team is especially valuable.

A good part of the value of that support was precisely in detecting risks before they reached production.

A payment integration is also a coordination project

Another fundamental factor has been the coordination between teams.

The checkout does not end on the web. The company also has mobile applications for iOS and Android, maintained by another provider, and the behavior of the new system had to be consistent regardless of the channel used by the client.

Additionally, there were different internal areas affected by the change. Technology, business, Customer Service, and external providers had to understand what was changing, when it was changing, and what dependencies existed between teams.

In practice, much of the difficulty was not in the Checkout.com API but in coordinating the changes between web, mobile applications, payment provider, and internal teams.

An integration can be perfectly implemented and still fail if a team is unaware of a dependency, an application is not prepared for the change, or an incident reaches a person who does not know how to interpret it.

QA as part of the launch architecture

Probably one of the areas where we have been most meticulous has been QA.

We designed and executed specific testing plans on two differentiated QA scenarios, in addition to validating the corresponding flows in the iOS and Android applications.

But in a payment system, there is an evident limit to any testing environment. A sandbox can reproduce many behaviors, but it cannot fully replicate the real ecosystem composed of banks, cards, authentications, wallets, production configurations, and user behavior.

For this reason, we also conducted controlled tests against production from our stage environments. We did not want the launch day to be the moment when certain flows were executed for the first time against real systems.

When that day arrived, many of the critical situations had already occurred previously in a deliberate and controlled manner. We reached the launch with the main scenarios already validated, including those that could only be reliably checked against production.

Preparing for what happens when something goes wrong

There is a part of this project that we consider especially important and that, however, usually receives much less attention than the code.

Before the launch, we prepared a specific Action Plan for Customer Service. Because correctly implementing a payment platform does not mean assuming that there will never be rejected payments, failed authentications, expired cards, pending operations, or discrepancies that need review.

All those situations are part of the normal operation of any real payment system. The difference lies in whether the organization is prepared for them.

The goal of the plan was for Customer Service to recognize foreseeable situations, know what information to request, what response to provide to the user, and when to escalate the case to the technical team.

This way, we avoid the first appearance of a known situation forcing the team to improvise a response.

For us, this point summarizes a good part of the philosophy of the project:

A migration does not end when the new system processes correctly. It ends when the organization knows what to do when something does not go as planned.

The launch

The implementation affects five markets, three of which are currently operational and two in preparation, and includes web, mobile applications, multiple payment methods, and tokenization and recurrence processes.

The launch was carried out with:

• zero service interruptions;
• a single minor incident, resolved quickly;
• coordinated operation on web, iOS, and Android;
• coexistence with pre-existing payment methods;
• procedures prepared for the main operational scenarios after the launch.

It was not, therefore, about avoiding complexity, but about identifying it beforehand and being proactive.

The integration is the easy part

After projects like this, it is tempting to attribute success to a specific architecture, an API, or a particular technical decision. Naturally, the quality of the implementation matters. But the factors that truly reduce risk are others: understanding the existing system, identifying dependencies, coordinating all parties, testing real scenarios, and preparing the organization to operate the new system.

Especially when we work with legacy platforms. There is a lot of critical software running on systems that have been evolving for ten, fifteen, or twenty years. Completely replacing them is not always reasonable or necessary.

In many cases, the real engineering work consists precisely of evolving those systems without stopping the business that depends on them. That is what we have done in this project.

On August 20, we activated Checkout.com in production. The platform continued to operate normally, the previous payment methods continued to coexist with the new ones, and the only incident detected was minor and resolved without service interruption. In a system with more than ten years of history, five markets, and several sales channels, that was exactly the result we were looking for.