Open-source Ecommerce

April 03, 2026

Ecommerce Payment Integration Without Lock-In

Adyencomposable commerceHeadless eCommercePayment Integrationstripe

Most ecommerce platforms force you into a single payment provider or charge extra fees for using your own. A composable eCommerce stack treats payments as a layer you own, not a dependency you rent. That means connecting Stripe, Adyen, PayPal, or any PSP through one unified API, without rebuilding your checkout every time you switch providers.

Key Takeaways

Last verified: April 2026

The problem: Most platforms lock you into one payment provider or charge 0.2-2% platform fees on top of your PSP’s rates.

The approach: A unified Payment Sessions API abstracts the PSP layer so your checkout code stays the same regardless of provider.

Why it matters: You negotiate directly with payment providers, add local methods per market, and never pay platform transaction fees.

Why Ecommerce Payment Integration Is Harder Than It Should Be

Payment processing is the single point of failure in any ecommerce operation, yet most platforms treat it as an afterthought. You pick a payment provider during setup and then discover, twelve months later, that switching means rewriting your checkout, re-collecting saved cards, and negotiating with your platform vendor for data portability.

The numbers make this concrete. Global ecommerce payment processing reached $173 billion in 2025 (Precedence Research, 2025), growing at nearly 20% annually. With that growth comes fragmentation: digital wallets now account for 70% of Asia-Pacific ecommerce transactions, while bank transfers handle 36% of European online payments (PCMI, 2025). A single payment provider cannot cover every market.

As Adyen’s 2025 Retail Report put it: “The most successful merchants offer an average of 8.4 payment methods per market, compared to 3.2 for underperformers.” The question is whether your platform makes it easy to add providers or makes it painful.

Three patterns emerge when platform-level payment integration goes wrong. First, PSP lock-in: the platform only supports one gateway natively, and adding alternatives requires custom development. Second, platform transaction fees: you pay your PSP’s processing rate plus a 0.2-2% surcharge to the platform itself, simply for the privilege of processing payments on their infrastructure. Third, checkout fragmentation: every new PSP requires a different frontend integration, different webhook handling, and different error flows.

A headless eCommerce platform with a properly abstracted payment layer eliminates all three.

How Platform Transaction Fees Add Up

Platform transaction fees are the hidden cost most merchants discover too late. You negotiate a competitive rate with Stripe (say, 2.15% + $0.30 per transaction), then discover your platform charges an additional 0.2% on every transaction processed through a third-party gateway. On $10 million in annual revenue, that is $20,000 in fees you are paying for nothing except the platform’s permission to use your own payment provider.

The fee structures vary, but the pattern is consistent. A merchant doing $15 million annually on a platform with a 0.5% third-party transaction fee loses $75,000 per year. At 2%, the number reaches $300,000. These are not processing fees for a service rendered. They are a toll for using a payment provider the platform did not choose for you.

Open-source commerce platforms eliminate this entirely. There is no platform entity collecting a percentage of your transactions. You pay your PSP and nobody else. For a $15 million brand, the $75,000-$300,000 saved annually covers the total cost of ownership for an open-source deployment several times over.

With Spree Commerce: Zero platform transaction fees, regardless of which payment provider you use. Connect Stripe eCommerce integration, Adyen eCommerce integration, PayPal, or any custom gateway. You pay the PSP’s rates and nothing more. That is what built-in eCommerce features mean in practice: the platform does not tax you for using its own capabilities.

How Do Marketplace Payment Integrations Handle Split Payments?

Marketplace eCommerce payment integration adds a critical layer of complexity: money flows not just from customer to merchant, but from customer to marketplace to multiple vendors, with commissions deducted at each step. Getting this wrong means manual reconciliation, delayed vendor payouts, and regulatory exposure.

The infrastructure for this exists in two forms. Stripe Connect handles automated split payments, configurable marketplace fees, and vendor onboarding with identity verification. Adyen for Platforms provides the same capabilities for enterprises that need Adyen’s global payment network, advanced fraud protection, and support for 150+ currencies with location-aware payment methods.

A European FMCG conglomerate launching a subscription marketplace across 22 countries, for example, needs per-country payment methods (iDEAL in Netherlands, Bancontact in Belgium, SEPA across the EU) with automated commission splitting per vendor. That is not something you bolt onto a checkout integration. It requires platform-level marketplace checkout with split payments where the payment layer understands vendors, commissions, and multi-currency settlement natively.

With Spree Commerce: The open-source marketplace platform includes Stripe Connect payouts and Adyen for Platforms as part of Enterprise Edition. Vendor onboarding and commission management are built in. Configurable commission rates per vendor, per category, and per product. No third-party marketplace plugins required.

What Payment Methods Do B2B Buyers Actually Need?

B2B eCommerce payment methods look nothing like consumer checkout. A procurement buyer at a $50 million industrial supplier does not enter a credit card number. They submit a purchase order, expect net-30 terms, and pay via bank wire after the goods arrive. Forcing B2B buyers through a consumer checkout flow is the fastest way to kill adoption.

The challenge is supporting both worlds simultaneously. Your wholesale buyers need purchase orders, bank transfers, and cash-on-delivery options. Your SMB customers need credit cards and digital wallets. Both buyer types need to coexist in the same platform without separate checkout flows or parallel systems.

This requires payment methods that do not go through an external payment session. When a B2B buyer submits a PO, the order completes immediately. The payment is tracked as pending until the wire clears or the check arrives. The merchant captures the payment from the admin panel once the physical payment is received.

With Spree Commerce: Check, bank transfer, cash on delivery, and purchase order methods work alongside card and wallet gateways like Stripe and Adyen in the same checkout. No workarounds, no separate checkout flows. A B2B eCommerce platform with approval workflows for B2B buyers means procurement teams get the purchase order flow they expect, while consumer buyers get the card and wallet options they expect, all from the same backend.

Why Local Payment Methods Make or Break International Expansion

Offering only credit cards in a market where 71% of consumers pay with digital wallets is not a payment strategy. It is a conversion filter. When a Dutch shopper cannot pay with iDEAL, or a Chinese customer cannot use Alipay, the cart abandonment rate tells the story.

The data is clear: digital wallets account for 70% of ecommerce transactions in Asia-Pacific, while bank transfers and local methods handle 36% of European online payments (PCMI, 2025). A beauty brand expanding from the US to 12 European markets cannot rely on a single PSP that covers credit cards globally but misses local favorites.

The composable approach solves this by letting you connect different PSPs per market. Stripe for your US operations. Adyen for European markets where its Drop-in component automatically surfaces the right local methods based on the customer’s location. A regional provider for a specific country where neither global PSP has strong coverage. Each provider connects through the same payment session interface, so your storefront code does not change.

With Spree Commerce: Markets provide per-market currencies, languages, payment methods, and shipping rules from one instance. Stripe supports 130+ currencies. Adyen supports 150+ currencies with location-aware payment method selection. Configure different PSPs per store through the multi-region eCommerce architecture. Your checkout automatically surfaces the right methods for each customer without frontend changes.

How to Add a New Payment Provider Without Rebuilding Checkout

Adding a new PSP should take days, not months. With a properly abstracted payment layer, your team builds one connector for the new provider, configures it in the admin panel, and it appears as an option at checkout. Your storefront code, webhook handling, and order management all remain unchanged.

The pattern is the same every time. The new provider plugs into the same payment session flow that Stripe, Adyen, and PayPal already use. Your commerce platform handles the coordination. The connector handles the provider-specific translation. When you add a new PSP, you write one connector. The rest of the system already knows how to work with it.

This matters practically when your business changes. You start with Stripe because it is developer-friendly and self-serve. Two years later, your enterprise sales team closes a deal with a customer that requires Adyen for compliance reasons. With a composable payment layer, adding Adyen is a configuration change, not a re-architecture. With a monolithic platform, it is a project.

With Spree Commerce: The custom payment gateway integration guide walks your team through building a connector for any provider. Once connected, the new gateway works with your existing checkout, webhooks, and admin panel without touching your storefront. The REST API documentation covers every endpoint, and the TypeScript SDK (@spree/sdk) gives your frontend team typed client methods for every payment operation.

What Happens When the Customer Closes the Browser Mid-Payment?

Payment reliability is the unglamorous but critical piece of payment integration. The customer authorizes a payment via 3D Secure, gets redirected back to your site, and closes the browser before the frontend can confirm the order. Did the payment go through? Is the order complete? Is the customer going to see a double charge?

Most ecommerce platforms handle this poorly. The payment succeeds on the provider’s side, but the order sits in limbo because the customer’s browser never confirmed it. The merchant discovers a paid-but-incomplete order during reconciliation. The customer contacts support. Everyone wastes time.

The fix is server-side confirmation. When a payment succeeds, the payment provider notifies your commerce backend directly. The backend verifies the payment, records it, completes the order, and sends the confirmation email, regardless of what the customer’s browser did. If the customer’s browser also sends a confirmation (because they stayed on the page), the system recognizes the order is already complete and avoids double-processing.

With Spree Commerce: Every configured PSP shares one webhook endpoint. When a payment succeeds, the platform automatically verifies the signature, records the payment, completes the order, and sends the confirmation email. You do not build separate webhook routes for Stripe, Adyen, and PayPal. You configure each provider once, and the platform handles the rest. Orders never get stuck in limbo because payment confirmation and order completion happen server-side, regardless of what the customer’s browser does.

Choosing the Right Ecommerce Payment Integration for Your Stack

The decision comes down to three questions. First, do you need PSP flexibility, or are you committed to a single provider for the foreseeable future? If flexibility matters, your platform must abstract the payment layer.

Second, do you operate (or plan to operate) in multiple markets where local payment methods determine conversion rates? If so, you need per-market PSP configuration, not a one-size-fits-all gateway. Third, do you run (or plan to run) a marketplace with vendor payouts? Payment splitting must be built into the platform, not bolted on.

Requirement	What to Look For	Red Flag
PSP flexibility	Unified payment API, multiple gateway support	Only one supported gateway
Zero platform fees	Open-source, no transaction surcharge	“Third-party gateway fee” in pricing
Marketplace payouts	Native split payment support	“Marketplace plugin” required
B2B payment methods	PO, bank transfer, net terms alongside cards	Consumer-only checkout
Local payment methods	Per-market PSP configuration	Single global gateway
Webhook reliability	Server-side completion for browser-closed scenarios	Frontend-only order completion

For teams building on a headless eCommerce platform with a composable architecture, the payment layer should be one of the simplest integration decisions, not one of the most constraining. The open-source Next.js eCommerce storefront includes a working payment integration with Stripe out of the box, demonstrating exactly how the Payment Sessions API works in a production frontend.

What Does a Composable Payment Architecture Look Like?

A composable payment architecture separates your commerce backend from any specific payment provider. Your storefront talks to one API. That API handles the translation between your checkout and whichever PSP you configure, whether that is Stripe today, Adyen tomorrow, or a regional provider for a specific market.

The key abstraction is a payment session. Instead of your frontend calling Stripe’s API directly (which couples your checkout code to a single provider), the frontend creates a session through your commerce backend. The backend then coordinates with whichever PSP is configured for that store, currency, or payment method. Your frontend code does not change when you add a new provider.

Here is how the flow works:

Step	What Happens	Who Is Involved
1. Create session	Frontend requests a payment session for the selected method	Commerce API + PSP
2. Collect payment	Frontend uses the PSP’s SDK to securely collect card or wallet data	PSP SDK + Customer
3. Complete session	Frontend confirms payment, commerce backend verifies with PSP	Commerce API + PSP
4. Finalize order	Frontend completes the order after payment is confirmed	Commerce API

This four-step pattern works identically whether the customer pays with a credit card via Stripe, a bank transfer via Adyen, or Apple Pay through either provider. The frontend code does not know or care which PSP is behind the session. That is the entire point: your eCommerce payment architecture becomes provider-agnostic.

With Spree Commerce: The Payment Sessions API implements exactly this pattern. One unified interface handles Stripe, Adyen, PayPal, and any custom gateway through a single set of endpoints. Card data never touches your server because the PSP’s frontend SDK collects it directly, keeping you PCI-compliant by default.

Frequently Asked Questions