Help for owners
Checkout stopped working after an Adyen Drop-in or Web Components update
Short answer
Adyen ships breaking changes only in major versions of Drop-in and Components, and each major version needs a minimum Checkout API version. An update that moved a major version without the matching API, or without changed code, can break checkout. Rolling back to the last working version is the safe first move.
Does this sound like your situation?
- The payment form no longer appears or shows an error.
- It broke right after a package update or a developer's release.
- Card payments fail but other methods still work.
- 3D Secure steps stopped working.
- My developer says the version on my site no longer matches the server.
Why does this happen?
Major versions carry the breaking changes
Adyen states that Drop-in and Components follow semantic versioning: backwards-compatible changes arrive in minor versions and breaking changes only in major versions. A move across a major version is a real change for your checkout, not a routine refresh.
Confirmed by docs.adyen.com
Each version needs a minimum server version
Adyen says to check the release notes for the minimum Checkout API version before a major upgrade. For example, Web Drop-in and Components v5.0.0 requires Checkout API v68 or later. A front end upgraded alone can be talking to a server that is too old.
Confirmed by docs.adyen.com
3D Secure depends on the API version
Adyen advises upgrading the Checkout API if you use 3D Secure 2 with v66 or earlier, because v67 added auto-authorisation. Card payments needing extra authentication are where an old server version shows first.
Confirmed by docs.adyen.com
Old versions are not kept alive
Adyen recommends the latest major Drop-in and Components version and says it no longer upgrades earlier major versions. A deprecated version gives you one year to upgrade, and an end-of-life version gets no support and payment processing can be suspended.
Confirmed by docs.adyen.com
Platform requirements move too
Adyen's compatibility tables tie each version to platform requirements. For example, iOS Drop-in and Components 5.13.0 needs Checkout API v71 and iOS 12, and Android 5.7.0 needs API v71, a minimum SDK of 21 and a target SDK of 34. A mobile app update can fail for these reasons.
Confirmed by docs.adyen.com
What can I do about it today?
- Ask what changed and whenFind out which package or version was updated, by whom and on what date. This is the best clue.
- Roll back to the last working releaseIf your developer can, redeploy the previous release of the site or app. A tested rollback is the quickest way to get paid again.
- Take a test payment on the live pageAfter any change, make a real small payment yourself and check it appears in Adyen before telling customers it is fixed.
- Do not update again to see if it helpsMore version changes on a broken checkout add new unknowns. One change at a time.
- Pause promotions or advertsIf checkout is down, avoid paying to send people to it until it works.
When should I bring someone in?
- A rollback is not possible or does not fix it.
- You use a mobile app and the store version is already live.
- Nobody can say which Checkout API version your server uses.
How do I handle it?
- Compare versions on both sidesI check the Drop-in or Components version in the front end and the Checkout API version on the server against Adyen's release notes.
- Reproduce it in the test environmentI recreate the failure with test cards, including a 3D Secure card, before touching the live site.
- Upgrade deliberatelyIf a major upgrade is needed, I follow Adyen's upgrade guides, changing the server and front end together and testing each payment method.
- Leave a rollback and a version noteYou get a short note of the versions in use and how to return to the last good release.
The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.
What do owners ask about this?
Can I stay on the old version?
For a while. Adyen says it no longer upgrades earlier major versions, a deprecated version gives you one year, and an end-of-life version can have payment processing suspended.
How do I hear about new releases?
Adyen suggests watching the adyen-web repository on GitHub and choosing release notifications.
Is the Adyen account affected?
Usually not. The break is between your checkout and the version it was built for.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.