Payment gateway module development for Magento, Adobe Commerce and Mage-OS

If you run a payment gateway, your merchants will ask for a plugin for whatever platform they're on, and the quality of that plugin becomes the quality of your product in their eyes. If you're a merchant, the gateway you need either has a module or it doesn't, and "it has one" turns out to mean very little on its own. We build payment gateway modules from scratch for Magento Open Source, Adobe Commerce and Mage-OS, and we maintain them for years afterward. This page is what that work actually involves, drawn from modules we still ship updates for.

Who needs a custom payment gateway module?

Two different people arrive at this question, with almost nothing in common except the deliverable.

You're a payment provider. You have an API, a sandbox, and a growing list of merchants who need you inside their checkout. Every platform you don't have a plugin for is a deal you can't close, and every plugin you ship badly is a support queue you inherit forever. You need someone who has done this against a real gateway API, not someone learning Magento's payment framework on your budget.

You're a merchant. You want a specific gateway at checkout: a local acquirer, a buy-now-pay-later provider, a processor with rates your current one won't match. Maybe a module exists and is three Magento versions behind. Maybe it exists and breaks guest checkout. Maybe it doesn't exist and the provider is happy to cooperate but has nobody to build it.

Both end up needing the same thing: a module built on the platform's own payment framework, tested against the gateway's sandbox, and maintained as both sides change underneath it.

What does a payment gateway module actually have to do?

More than "call the API." The parts that are genuinely required, roughly in the order a payment moves through them:

• Authenticate against the gateway and manage credentials per store, including refreshing tokens that expire and caching ones that don't.
• Decide when to offer itself. Country, currency, cart minimum and maximum, customer group, product eligibility. Wrong here means the method shows up where it can't be used, and your checkout collects complaints.
• Move the customer through the payment. Redirect out and back, or an inline form, or a hosted iframe, each with different failure modes.
• Decide when an order exists and what state it's in. This is the hard one, and it's the subject of its own post below.
• Receive and trust webhooks. A public endpoint that moves money, which anyone can POST to. Signature or payload verification, idempotency, and state guards are not optional.
• Handle the unhappy paths. Abandoned payments, invalid responses, double submissions, customers who close the laptop mid-flow, retried webhooks.
• Invoice, email, refund. Including not emailing a confirmation for a payment that hasn't landed.
• Be configurable and debuggable by someone who is not you: standard admin config, per-website scope, a log the merchant's developer can read.

Every one of those is a place we have watched a payment integration fail in production, which is why the list reads like it does.

Why "it's just an API integration" is the expensive assumption

The API calls are the easy part and usually the first afternoon. The cost lives in the timing, the trust boundaries, and the platform's own opinions about order state. Concretely, from work we've shipped:

• Order-flow timing. Create the order after the gateway confirms and you keep a clean order table, but a payment can land with no order behind it. Create it before the redirect and you inherit abandoned pending orders that need sweeping. We shipped it the first way, then inverted it, because a complete order table beats a tidy one every time.
• Webhook trust. Verify the signature before you hand the body to a JSON parser, not after. Guard on order state so a retried webhook is idempotent instead of a second invoice.
• Guest checkout. Guests carry a masked quote ID, not a real one. Miss that and a whole segment of buyers hits a payment error and silently leaves.
• Multi-store scope. Credentials, terms, and enablement are per website. A module that reads global config works perfectly until the merchant launches a second brand.
• Double submission. A shopper who clicks Place Order twice on a slow connection should not be charged twice.
• Email timing. The confirmation belongs after the invoice, not after the redirect.

None of these show up in a gateway's API documentation. They show up in production, in the merchant's support inbox, usually on a Friday.

Does a module for Magento work on Adobe Commerce and Mage-OS?

Yes, and that's worth saying plainly because the naming confuses people. Magento Open Source, Adobe Commerce and Mage-OS share the same core architecture. A payment module built properly on `Magento\Payment`, with its gateway facade, command pool and validator pool, installs and runs on all three.

What does differ:

| | Magento Open Source | Adobe Commerce | Mage-OS |
| --- | --- | --- | --- |
| Same payment framework | Yes | Yes | Yes |
| Composer install | Yes | Yes | Yes |
| Marketplace distribution | Adobe Commerce Marketplace | Adobe Commerce Marketplace | Composer / your own repo |
| Extra surfaces to test | Core checkout | B2B quotes, staging, multi-source | Distribution-specific patches |
| Release cadence to track | 2.4.x | 2.4.x plus Adobe patches | Its own, community-driven |

The practical difference is testing surface, not code. Adobe Commerce adds features a payment method can interact with, notably B2B quotes and negotiable pricing, so a module aimed at Adobe Commerce merchants needs to be exercised against those. Mage-OS moves on its own schedule, so compatibility is something you verify rather than assume. We target the range explicitly: our current Float module supports 2.4.6 through 2.4.7 on PHP 8.3, and we say so in the readme, because "should work" is not a compatibility statement.

What about Shopify, WooCommerce and OpenCart?

The same payment problems, but the platform decides how much of the solution you're allowed to own.

• Magento, Adobe Commerce, Mage-OS. Full server-side control of the checkout and order lifecycle. The most work and the most capability. Everything above applies.
• Shopify. You build an app, and the checkout is Shopify's. That constrains what a payment integration can do and where it can put its UI, and it means your integration lives inside someone else's policy. Worth reading our note on what that dependency costs when the policy changes.
• WooCommerce. A payment gateway class plus WordPress hooks. Fast to get running, and the discipline has to come from you rather than the framework.
• OpenCart. Still real business, especially for merchants who never left it. Older patterns, fewer guardrails, and version fragmentation to design around.

The order-state and webhook-trust problems are identical on all four. Only the enforcement changes.

How can you tell whether a payment module is actually maintained?

Ask for the changelog. Not the readme, not the marketplace listing, the changelog. Then look for three specific things:

1. Releases that track platform versions. Did it get a release when 2.4.6 landed? When PHP 8.3 became the requirement? A module with no compatibility releases is a module that will block a merchant's next upgrade.
2. At least one gateway API migration. Payment providers version their APIs. A module that has survived a `v1` to `v2` migration on a live install has been maintained by someone who was paying attention.
3. Boring bug fixes with specific names. "Fixed guest customer checkout payment option error" is a better signal than any feature. It means real merchants used it, hit something, and somebody fixed it.

Our Float module has all three across five years and eleven releases: 2.4.6 compatibility, PHP 8.3, a migration onto the provider's API v2.0, and a long tail of named fixes.

What we've built

| Integration | Platform | What it is | Status |
| --- | --- | --- | --- |
| Float Payments | Magento 2 / Adobe Commerce | Card-linked BNPL instalments, SA | 5 years, 11 releases, live |
| HyperSwitch PHP SDK | Framework-agnostic PHP | Full client for an orchestration API | MIT, 17/17 groups, ~83 endpoints |
| HyperSwitch module | Magento 2 / Adobe Commerce | Payment module on the orchestrator | In build, adopting the SDK |

Read the detail:

• Building a buy now, pay later payment module for Magento 2 from scratch - the original eight-week build, and why the instalment preview belongs on the product page rather than at checkout.
• Magento 2 orders stuck in pending payment: why we inverted our order flow - both designs, what each costs, and the cron you need either way.
• How we built and maintained the Float Payments Magento module - the five-year view, including webhook trust and the fixes that decide whether a merchant trusts a payment method.
• What HyperSwitch is and the PHP SDK we open sourced for it - orchestration, and who genuinely benefits from it.

More of the back catalogue is being written up; payment work has been a constant here far longer than the blog reflects.

How the work actually runs

No surprises in the process, because payment projects go wrong when expectations do:

1. Read the gateway's API properly and get sandbox credentials. Half the estimate lives here. An API with a versioned spec and a real sandbox is a different project from a Postman collection and a support email.
2. Agree the flow before writing code. Redirect or inline, when the order is created, what the webhook is authoritative for, what happens to abandoned attempts.
3. Build on the platform's payment framework, not around it. This is the difference between a module that survives upgrades and one that becomes the merchant's problem.
4. Automate the standards. Coding-standard checks and unit tests on the paths that touch money, in CI, from early on.
5. End-to-end against the sandbox, including the failure paths people skip: declines, timeouts, retried webhooks, double clicks.
6. Ship it where merchants can get it: Adobe Commerce Marketplace, a private Composer repository, or the provider's own distribution.
7. Then maintain it. Platform releases, PHP versions, gateway API changes. This is the part that determines whether the module is an asset or a liability in two years.

Frequently asked

Do I need a custom module, or can I use one that exists? If a maintained module exists for your gateway and platform, use it. We'll tell you when that's the answer. Custom is for when nothing exists, what exists is abandoned, or your gateway needs to hand merchants something it can stand behind.

How long does an initial build take? For a straightforward redirect flow against a documented API with a working sandbox, plan in weeks, not days. Float's first stable release came about eight weeks after the first commit, and that was a focused build with the provider responsive on questions. Inline card capture, tokenization, 3DS, split settlement or payouts each add scope.

Will it work on Adobe Commerce and Mage-OS as well as Magento Open Source? Yes. Same payment framework, same module. Adobe Commerce adds surfaces worth testing against, notably B2B quotes, and Mage-OS moves on its own release schedule, so we verify rather than assume.

Who owns the code? Whatever we agree up front. We've shipped both: proprietary modules owned by the payment provider, and open-source libraries under MIT. Decide it before the first commit, not at handover.

What happens after launch? Someone has to track platform releases, PHP versions and the gateway's own API changes. We do that on a maintenance arrangement, or we hand over a module documented well enough for your team to take it.

Talk to us about your gateway

If you're a payment provider who needs merchants to be able to install you, or a merchant who needs a specific gateway in your checkout, tell us which gateway and which platform and we'll tell you honestly what it involves, including when the answer is "use the module that already exists."

Get in touch, or read more about how we approach platform and API integrations and ecommerce development.