Skip to content

Adobe Commerce / Magento payment gateway integration, from checkout to ERP

Home / Blog / Adobe Commerce / Magento payment gateway integration, from checkout to ERP


Plenty of payment gateway projects on Adobe Commerce go wrong before anyone writes code. The gateway gets picked on its rates, the extension gets installed, the test orders go through, and the trouble shows up a month later. An order with no payment. A payment with no order. A bank deposit that nobody in finance can match to anything.

Adobe Commerce, Magento Open Source and Mage-OS all handle payments through the same framework, so Magento payment gateway integration works the same way on all three. The code is the small part. What decides whether the integration works is a handful of choices you make first, and most of them are about where the money goes after checkout.

This is the merchant's side of the job, written for whoever has to keep checkout, the gateway and the ERP in agreement. If you run a payment gateway and need a module built for your merchants, that's a different project, and we wrote it up separately: payment gateway module development for Adobe Commerce, Magento and Mage-OS.

What does Magento payment gateway integration actually involve?

A working integration does six jobs. Only the first one is visible at checkout.

  1. Show the payment method to the right buyers. By country, currency, customer group and order size.
  2. Take the card without your servers touching it, if you can help it. This decides your PCI work.
  3. Run 3-D Secure when the card's bank asks for it.
  4. Decide when an order is real, based on what the gateway says, not what the buyer's browser says.
  5. Capture, refund and void from the Adobe Commerce admin, so the order and the gateway never disagree.
  6. Hand the payment to your ERP with enough detail that finance can match the deposit to the orders inside it.

A gateway's extension is built to do the first five. The sixth sits between Adobe Commerce and your ERP, and no gateway extension can do it for you, because no extension knows your ERP.

Should you use the gateway's extension or build a custom module?

Use the existing extension when there is one and it's maintained. That's the right answer more often than not.

Adobe Commerce and Magento Open Source already include a few options. PayPal is part of the core code, Braintree ships as a bundled extension, and Adobe's own Payment Services is the option Adobe recommends. Authorize.Net, CyberSource, eWay and Worldpay left the core code in 2.4.0 and moved to official extensions on the Commerce Marketplace. Most of the large gateways publish an extension of their own.

Before you trust one, read its changelog, not its marketplace listing. Did it get a release for each 2.4.x version and each PHP version you'll run? Has it lived through a change to the gateway's own API? We go through what a healthy changelog looks like in the module development post.

A custom module is worth it when:

  • No extension exists, or the one that exists is stuck on old versions and will block your next upgrade.
  • You need the gateway to follow your ERP's rules. For example, capturing payment only when the ERP says the order shipped.
  • You need B2B data the extension won't send, like the extra purchasing card details covered further down.
  • Your "gateway" is really an orchestration layer that routes payments across several processors.

We build custom payment modules for a living, including a buy now, pay later module we started in 2021 and still ship releases for. We still send people to the extension when it's good enough. A module you don't need is a module somebody has to keep alive.

The gateways you don't use still cost you

While you're in the payment settings, look at what's installed and switched off. On one store we support, the bundled Braintree extension had never taken a single payment, and every Braintree method was turned off. It still loaded Braintree's JavaScript on every storefront page, for PayPal messaging in the mini cart. When that host was slow, pages waited for it. One of our test runs sat for 30 seconds. We removed the packages through Composer, and the wait went with them.

Hosted payment page, hosted fields or direct API: which should you choose?

There are three ways to take a card on Adobe Commerce. The choice decides how much security work lands on you.

Hosted payment page Hosted fields Direct API
What the buyer sees Leaves your site to pay, then comes back Card fields that look like part of your checkout Your own card form
Who handles the card number Only the gateway Only the gateway, inside its own frames Your server
PCI questionnaire, usually SAQ A SAQ A, if every field is the gateway's SAQ D
Where it breaks The trip back, when buyers never return Scripts and layout on your checkout page Everywhere, and you own all of it
Good fit Simple checkouts, gateways with a strong hosted page Most B2B and retail checkouts Rarely right for a mid-market merchant

For most stores, hosted fields are the sensible middle. The buyer never leaves, the card number goes straight from their browser to the gateway, and your servers never see it.

The one trap is a form your own page builds. If your checkout creates the card form and posts it to the gateway, that's called "direct post," and it moves you to SAQ A-EP. The PCI Council's rule is short: if any element of the payment page comes from your website, you're not eligible for SAQ A.

Which PCI questionnaire will your store be on?

Your acquirer decides which self-assessment questionnaire (SAQ) you file, so ask them. But you can predict it:

  • SAQ A when every part of the payment form comes from the gateway, by redirect or by iframe.
  • SAQ A-EP when your site builds the payment form but never receives the card number.
  • SAQ D when card numbers pass through your own server. It's the full assessment, and it's a very different amount of work.

One change from early 2025 matters if you use hosted fields. SAQ A now has an extra condition for stores that embed the gateway's form in an iframe: you have to confirm your site isn't open to script attacks that could affect it. The Council's FAQ 1588 gives two ways to meet it. You can protect the page yourself, with the kind of controls in PCI DSS requirements 6.4.3 and 11.6.1. Or you can get confirmation from your gateway that its embedded form, set up their way, already includes those protections. A plain redirect isn't covered by that condition.

So before you choose hosted fields, ask the gateway for that confirmation in writing. And treat your checkout as a payment page, which means knowing every script that runs on it. If nobody on your team can list them, that's one of the first things an Adobe Commerce security audit looks at.

Phone orders are their own channel. If your sales team keys in card numbers that buyers read out on the phone, ask your acquirer how that's assessed. That goes for the Adobe Commerce admin and for the gateway's virtual terminal alike. Staff typing a card number they heard is not the same as a buyer typing their own, and it often needs its own questionnaire.

Do you need 3-D Secure on an Adobe Commerce store?

If you take payments in Europe or the UK, yes, in practice. Strong Customer Authentication rules cover customer-initiated online card payments when both your payment provider and the buyer's bank are there, and 3-D Secure 2 is the main way to meet them. A US store selling to European buyers through a US account sits mostly outside those rules, though the buyer's bank can still ask for a check.

In the US it's optional. Its main job there is moving fraud chargebacks off you: when a buyer completes a 3-D Secure check, liability for a fraud dispute usually shifts to the card's bank. Disputes for other reasons, like "item not received," stay with you.

Most of the time the buyer sees nothing. Sometimes their bank asks for a code or an app approval, which is called a challenge. Your gateway's extension runs that step, but your checkout has to wait for it, and this is where a common failure hides:

  1. The buyer's bank asks for a challenge.
  2. The buyer closes the window, or it times out.
  3. The bank approves the payment anyway, a little later.
  4. The gateway now holds a successful charge. But the browser never came back to tell Adobe Commerce to place the order.

You have a payment with no order. Good extensions have a safety net for this. Some listen for the gateway's webhook and create the missing order. Others can create the order first, in Pending Payment, before the 3-D Secure step runs. Find out which one yours uses, and test the case on purpose: start a challenge in the sandbox, then close the window.

When is an Adobe Commerce order actually paid?

When the gateway says so, on its own channel. The buyer's browser landing on your success page is a hint. The webhook, the gateway's server calling yours, is the truth.

There are two ways to build the order flow. Create the order before the payment, and you get abandoned Pending Payment orders that need sweeping. Create it after, and you keep a clean order list, but a payment can land with nothing behind it. Our post on Magento 2 orders stuck in pending payment walks through both, and what each one costs.

Either way, the webhooks need the same care:

  • Check the signature first, before you trust anything in the message.
  • Expect the same webhook twice. The second one should change nothing.
  • Expect them out of order, and before the buyer's browser comes back.
  • Make sure they can reach you. A staging site behind a login gate or a firewall rule quietly blocks them, and you end up testing a flow that's only half there. We've run into this ourselves.
  • Log every one with the gateway's event ID, so "did we get it?" takes a minute to answer.

There's more on webhook trust in the story of a BNPL module we've kept running since 2021.

How do gateway payments get matched in your ERP?

This is the part finance notices. Three records have to agree:

  1. The Adobe Commerce order and its invoice.
  2. The gateway's transaction, and later the payout that includes it.
  3. The ERP's sales order, and the cash receipt applied against it.

The payout is where it falls apart. Most gateways don't deposit one order at a time. They pay out in batches, often after taking their fees and any refunds or chargebacks, and sometimes days after the order. Finance sees one deposit and has to work out which orders are inside it. If the ERP only knows the order number, and the gateway only knows its own transaction ID, someone ends up matching them by hand.

What fixes it:

  • Send the gateway's transaction ID to the ERP with the order. Adobe Commerce already stores it on the order's payment record; your order sync just has to carry it across. Whether the ERP is Epicor Prophet 21, NetSuite, Microsoft Dynamics 365 Business Central or SAP Business One, that ID is what lets someone apply the cash to the right invoice.
  • Send your order number to the gateway. Most gateways have a field for your own reference. Put the Adobe Commerce order number there, so one search in the gateway's dashboard finds the order.
  • Reconcile against the payout report, not the order list. The payout report is what the bank deposit is actually made of.
  • Refund in one place. A refund issued in the gateway's dashboard may never reach Adobe Commerce unless the extension listens for it. Even then, the ERP only hears about it if your sync sends credit memos. Refunding from the Adobe Commerce admin, with an online credit memo, keeps all three in step.
  • Decide who captures, and write it down. For a distributor, the ERP usually knows when an order ships. If you capture on shipment, either the ERP tells Adobe Commerce to invoice, or the capture happens somewhere else and Adobe Commerce is told afterwards. Card authorizations also expire, on a window set by the card network and your processor, so a backorder that ships weeks later may need a fresh one.

If your order sync is still being designed, our guide to Adobe Commerce integration and the right API for each job covers that side. If your ERP is Epicor Prophet 21, we've written about what that sync takes, too.

What about B2B buyers who don't pay by card?

Plenty of them don't. Distributors and manufacturers sell a lot on terms, and Adobe Commerce handles that without a gateway:

When you add a card gateway next to these, get two things right. First, show each buyer the methods that fit them: terms customers shouldn't be pushed to cards, and a brand new account shouldn't see Payment on Account. That's a matter of how payment method availability works at Magento checkout. Second, keep credit in one place. If the ERP owns credit limits, and it usually should, the store reads them from the ERP instead of keeping a copy that drifts.

When B2B buyers do pay by card

It's often a purchasing card, and two details are worth the effort.

Level 2 and Level 3 data. Purchasing and corporate cards can qualify for lower processing rates when you send extra detail with the payment: the tax amount and PO number (Level 2), and the line items (Level 3). The rules are moving. Visa has been replacing its US Level 2 and Level 3 programs with a new Commercial Enhanced Data Program, while Mastercard still uses Level 2 and Level 3. Ask your processor what it wants today, then check whether your extension sends it.

A statement name your buyers will recognize. People who pay by purchasing card reconcile their statement every month, line by line. A buyer on one of our calls this summer spent part of it trying to place a charge whose name was cut off halfway. Most gateways let you set the name that shows on the card statement, and some let you add the order number to it. Use both.

How do you test a payment gateway integration before go-live?

In the gateway's sandbox, on purpose, including the cases people skip:

  • Approved, declined, insufficient funds and expired cards.
  • A 3-D Secure challenge passed, failed, and abandoned by closing the window.
  • Place Order clicked twice on a slow connection.
  • The same webhook delivered twice, and one that arrives before the browser comes back.
  • Full and partial refunds from the admin, and one started in the gateway's dashboard.
  • A guest, a logged-in buyer, and a buyer on a company account.
  • A second website or store view with its own payment settings.
  • The order in your ERP. Does it carry the transaction ID? Does the refund reach it?

Automate what you can. On one store we support, our Playwright checkout tests buy a product twice, once as a guest and once as a registered customer. Then they check the order's state, its single invoice and the gateway's transaction ID in the database. Before a single card number is typed, they also check that the payment key the checkout gives the browser is a sandbox key, and stop if it isn't. That check is cheap insurance against a test run charging a real card.

For go-live, deploy the new extension switched off, and turn it on at a quiet hour. Place one real low-value order and refund it. Then watch the first payout arrive and make sure finance can match it in the ERP. That last step is the real finish line.

Frequently asked

Does Adobe Commerce (Magento 2) come with payment gateways built in? A few. PayPal is in the core code, Braintree comes as a bundled extension, and Adobe offers Payment Services. There are offline methods too: Check / Money Order, Bank Transfer, Cash on Delivery and Purchase Order, plus Payment on Account with Adobe Commerce B2B. Everything else is an extension.

Will the same payment extension work on Adobe Commerce, Magento Open Source and Mage-OS? Usually, yes, because they share the same payment framework. Check the extension's stated version range against yours. On Adobe Commerce, also test it against the B2B features you use, like company accounts and purchase orders.

Can we keep our own payment processor? On Adobe Commerce, yes. The platform doesn't tie you to one, so you pick a gateway that works with your merchant account.

Can we run two gateways at once? Yes. Most payment settings can be set per website, so you can run a different gateway per region or brand, or run the old and new side by side while you switch.

Who handles PCI compliance, us or the gateway? Both. The gateway is responsible for its systems, and you file your own questionnaire every year with your acquirer. Hosted fields or a hosted page make yours much shorter. They don't make it go away.

Where to start

If you're partway through one of these, start from the end and work backwards. Where does the money land, and can finance match it without asking you? Once that answer is clear, the extension choice, the PCI questionnaire and the webhook design mostly follow from it.

So which one is giving you trouble right now: picking the extension, the PCI paperwork, or the deposit that never quite matches? Our payments and checkout work covers all three, and if you write to us with the gateway and the ERP you're on, we'll say which of the six jobs we'd look at first.


Written by X2Y.DEV
Payments Payment Gateway Adobe Commerce Magento Mage-OS ERP Integration
Back to Blog

0%