Payment Gateway Integration in Expo Apps: A Practical Guide

If you've ever had an Expo checkout look perfect in staging, then watched live payments stall, misfire, or never show up in your database, you already know the problem. The SDK call is the easy part. The work starts when a user closes the app mid-payment, a bank challenges the charge, or the gateway updates status after your screen is gone.

Payment gateway integration has moved from a niche checkout utility to core commerce infrastructure. One industry estimate valued the market at USD 26.7 billion in 2024 and projected USD 48.4 billion by 2029 with a 12.6% CAGR, while another forecast puts it at USD 48.17 billion in 2025 and USD 245.71 billion by 2033 with a 22.7% CAGR from 2026 to 2033 (market forecast context). In parallel, implementation speed has become a product advantage, with API-first payment platforms reported to cut setup time by up to 50% or even 66% in some modern implementations (implementation speed summary).

For indie teams, startups, and agencies, that changes the decision entirely. Payment gateway integration is not a back-office task anymore, it's a conversion lever, a market-access decision, and a release-risk decision. If your checkout doesn't support the payment methods your users expect, you're not just making the flow awkward, you're increasing the chance that the user bounces, especially when cart abandonment is already high and poor payment experience is a known culprit (checkout friction and consumer expectations).

A solid integration also isn't just “connect Stripe.” It's a full control flow: choose the gateway, wire credentials, move payment logic into a backend route, confirm status through webhooks, test declines and timeouts, then go live. If you want a good companion example while thinking through supported payment models, setting up Stripe and PayPal for crowdfunding is a useful adjacent read, because it shows how gateway choice affects the shape of the checkout, not just the button you render.

Table of Contents

• The Hidden Cost of a Half-Built Checkout
  • The seven-step flow that ships
  • Why payment methods matter as much as code
• Choosing a Gateway That Fits an Expo + Hono Stack
  • What to optimize for first
  • A shortlist for Expo + Hono teams
• Wiring the SDK and Your First Hono Payment Route
  • Keep the keys in the right place
  • Match the gateway SDK to the Expo config story
• Building the Expo Checkout Sheet with Apple Pay and Google Pay
  • Build the sheet in layers
  • Handle failure like a normal path
• Webhooks as the Only Source of Truth in Hono
  • Verify the event before you trust it
  • Handle duplicates with idempotency
• Sandbox Testing That Catches Production Bugs
  • Test the states your app will see
  • Read the webhook, not the browser
• PCI Scope, Local Methods, and Your Go-Live Checklist
  • Don't ignore regional payment behavior
  • Your go-live board checklist

The Hidden Cost of a Half-Built Checkout

A half-built checkout feels productive because it is easy to demo. The card form loads, the SDK returns something useful, and the happy path makes everyone relax. Then production starts doing production things. Users close the app during 3-D Secure, banks reply asynchronously, and your order table never learns what happened.

That is the difference between a demoable integration and a charges-in-production integration. The first one proves your UI can talk to the gateway. The second one proves your app can survive payment reality, which includes browser interruptions, webhook retries, refunds, and the slow mismatch between what the client saw and what the processor decided. For a fuller control-flow example, see the AppLighter-style route layer for booking and payments, because the backend shape matters as much as the SDK.

Practical rule: if the browser response is the only place you check payment status, you do not have an integration yet, you have a guess.

The seven-step flow that ships

The control flow that holds up in production is straightforward, but each step matters:

1. Choose the gateway and integration method.
2. Obtain merchant credentials and API keys.
3. Build the backend payment logic.
4. Wire the frontend checkout.
5. Handle webhooks as the source of truth.
6. Test sandbox declines, refunds, and timeouts.
7. Switch to live mode only after the previous six work.

That sequence lines up with practical integration guidance that starts with gateway selection, merchant setup, API credentials, sandbox verification, and go-live readiness (technical integration flow). It also matches what teams discover after the first live failure. A frontend-only success state is not enough, because the gateway can update the transaction after the app has already moved on.

For startup teams, the cost of skipping steps is time. You can often build a simple, demo-worthy flow quickly, but production hardening takes longer because you are wiring trust, not just buttons. That is why payment choice should sit beside onboarding and pricing in product planning, not in a last-minute sprint ticket.

Why payment methods matter as much as code

A checkout that only accepts one or two options creates friction for users who already expect flexibility. Compiled market guidance notes that 85% of consumers expect businesses to offer multiple payment methods at checkout, and that poor payment experience is one of the leading reasons shoppers abandon carts, in a market where overall abandonment is cited at 70% (consumer expectation and abandonment context). For an Expo app, that means Apple Pay, Google Pay, cards, and region-specific methods are part of the product, not extras.

A thin payments flow also shows up in investor demos and partner launches. If you need a reference point for the merchant-facing side, the same structural gap shows up in setting up Stripe and PayPal for crowdfunding, where the checkout needs to hold up across more than one payment path.

One weekend gets you the integration. It does not get you the confidence, unless you wire the backend, the webhook handler, and the test matrix together as one system.

Choosing a Gateway That Fits an Expo + Hono Stack

The right gateway for an Expo app is the one that fits your config plugin story, handles mobile wallets cleanly, and verifies webhooks without drama in an edge-friendly backend. That matters more than brand familiarity. An SDK that looks great in a web demo can become a dead end once you need Apple Pay entitlements, Google Pay support, or a clean server-side signature check in Hono.

What to optimize for first

For indie React Native teams, I'd rank the decision criteria like this, in order:

• Expo compatibility, because native module friction can slow you down before you've shipped anything.
• Mobile wallet support, because Apple Pay and Google Pay reduce friction in the exact place where users hesitate.
• Webhook verification, because your backend has to trust signed events, not browser states.
• Local payment-method coverage, because card-only flows can underperform in some regions.
• Early-stage operational simplicity, because you need something you can maintain.

The practical trade-off is simple. Stripe is often the easiest place to start for SDK quality and ecosystem depth. Adyen makes more sense when you need broader enterprise-style payment orchestration. Mollie, Razorpay, and Paystack can be better fits when regional methods matter more than having the most polished global brand.

A shortlist for Expo + Hono teams

The key isn't to pick the “best” gateway in the abstract. It's to pick the one whose SDK fits your Expo setup and whose webhook verification is clean enough to run in your Hono worker without awkward workarounds. If the backend verification story is messy, the integration will stay fragile no matter how pretty the frontend looks.

A useful internal reference for teams building this kind of stack is the booking source code overview, because it's a good reminder that a payment system lives inside a broader app architecture, not in isolation.

Wiring the SDK and Your First Hono Payment Route

The first working integration is usually smaller than people expect. The app should collect payment intent data and present the checkout UI. The Hono route should create the gateway-side object, return the minimum client payload, and keep the secret key out of the mobile bundle.

Keep the keys in the right place

Your publishable key belongs in the Expo app because it identifies the client, but it can't authorize sensitive server actions. Your secret key stays in the Hono worker because that's what creates and updates payment objects. If those two roles get mixed, the app becomes harder to secure and harder to debug.

The route shape should stay boring:

• The app sends an amount, currency, and customer context.
• Hono validates the request.
• Hono calls the gateway API.
• Hono returns the client secret or equivalent confirmation token.
• The app uses that token to confirm the payment in the UI.

That's the part most docs compress into a single code snippet, but the split matters. The frontend should only initiate and confirm. The backend should decide what's allowed, what's logged, and what gets persisted.

Match the gateway SDK to the Expo config story

In an Expo app, the integration gets easier when the gateway's React Native support fits the config plugin pattern cleanly. That's where Apple Pay entitlements and Google Pay setup stop being a future problem and become a normal part of app configuration. If the gateway expects hand-edited native projects too early, the setup burden grows fast.

For a simple stack, a Hono route can expose a payment-intent creation endpoint, then your Expo screen calls it before rendering the native payment flow. If you're comparing gateways, a useful starting point is a payment platform overview, because it helps you think about the gateway as a platform layer rather than a single checkout endpoint.

Keep the server response tiny. The more business logic you push into the client, the more brittle your checkout becomes when the network drops or the app is backgrounded.

The first end-to-end charge should feel almost anticlimactic once the stack is wired correctly. That's the goal. If the flow takes more than a screen and a route to reason about, the architecture probably needs simplification before you add more payment methods.

Building the Expo Checkout Sheet with Apple Pay and Google Pay

A diagram outlining the three steps to build an Expo checkout sheet for credit card, Apple, and Google payments.

The checkout sheet should present three clear paths, not one overloaded form. Manual card entry still matters, especially for fallback cases and testing. Apple Pay and Google Pay should sit beside it as native options, not buried behind extra taps.

Build the sheet in layers

Start with the card collection form. Keep the fields minimal, because every extra field adds friction and makes mobile typing worse. Then add the native Apple Pay button, gated by module availability, so supported devices can take the faster path. Finally, wire Google Pay through the gateway's React Native support so Android users get a native wallet flow too.

The important part is not which button appears first. It's that the screen treats each method as a way to initiate checkout, not as a separate business rule engine. The app shouldn't decide whether the charge succeeded. It should ask the gateway to confirm and then wait for server-side confirmation.

Handle failure like a normal path

Payments fail in mundane ways. Users cancel the sheet, connectivity drops, and 3-D Secure pops a challenge modal that interrupts the flow. Your Expo Router modal should treat those states as expected, not exceptional.

A clean client response looks like this in practice:

• User cancellation, close the modal and preserve the cart.
• Network errors, show a retry state without losing the collected details.
• 3-D Secure challenges, open the challenge sheet and hand control back to the gateway UI.
• Success callback, store only the minimum local state and wait for server confirmation.

The gateway platform still owns the true transaction outcome. The app owns the user experience. Those are different jobs, and the checkout stays far more stable when you keep them separate.

Webhooks as the Only Source of Truth in Hono

A diagram illustrating why webhooks are the authoritative source for payment status compared to client-side actions.

A successful client.confirmPayment() call is not the same thing as a confirmed charge. The client only initiates the flow. The gateway may still be waiting on a bank response, a fraud step, or an asynchronous settlement update. If you mark the order paid from the client response alone, you've turned a payment system into a guessing machine.

Verify the event before you trust it

The Hono webhook route should read the raw request body, verify the gateway signature, then persist the event before touching the order state. That order matters because webhook handlers are where malicious requests, replay attempts, and malformed payloads try to sneak in. If the signature check fails, the handler should stop immediately.

Once the event is verified, write it to your database layer, then update order state from the event type. A Supabase-backed Vibecode DB adapter works well for this pattern because it gives you a clear persistence layer between the webhook and the rest of your app.

The event itself is the source of truth. The client is only one signal, and it's the least reliable one for final status.

Handle duplicates with idempotency

Gateways can deliver the same webhook more than once. That's normal. Your handler should use an idempotency key or event identifier so the same payment event doesn't get applied twice.

A sane Hono flow looks like this:

1. Verify the signature against the raw body.
2. Check whether the event ID already exists.
3. Store the event if it's new.
4. Update the order only once.
5. Ignore duplicate deliveries safely.

For teams that want to tighten the surrounding API surface, these API security best practices are worth following alongside the payment route, because webhook endpoints are just another internet-facing surface if you don't protect them properly.

When the webhook handler is correct, frontend payment errors stop being financial failures. They become UX issues, which is where they belong. That's the main architectural win.

Sandbox Testing That Catches Production Bugs

A Sandbox Testing Checklist infographic for developers to test various payment gateway scenarios and transaction outcomes.

Sandbox testing only pays off when you script the ugly paths, not just the happy one. A clean authorization is the baseline. Declines, timeouts, refunds, and recurring renewals are what tell you whether the integration will hold up for live money.

Test the states your app will see

Your sandbox matrix should cover the states the checkout flow can reach in production, because those are the cases that break support queues and reconciliation.

• Successful authorization, to confirm the end-to-end happy path.
• Declined card, to make sure the UI handles failure cleanly.
• Insufficient funds, to confirm the error message is meaningful.
• 3-D Secure challenge, to validate challenge handling and modal recovery.
• Full refund, to check reversal logic and status updates.
• Partial refund, to ensure your state model can represent partial settlement outcomes.
• Payment void, to catch cancellations before capture.
• Network timeout, to verify retry behavior and webhook resilience.
• Recurring renewal, to make sure subscription-style billing doesn't break later.

The important part is what you assert after each event. In the database, the order should reflect the webhook outcome, not the browser message. If the transaction succeeded in the gateway but the client closed the app before the response came back, the webhook still has to update the state. That is why a real end-to-end test pass should include the backend route, the provider response, and the persisted order record, not just a tapped button in the app. If you want a practical testing framework to build around, end-to-end testing guidance fits this kind of payment validation well.

Read the webhook, not the browser

The technical pitfall is simple. A browser response can be lost, delayed, or never rendered. The webhook reaches your backend independently, which makes it the signal you can trust for fulfillment, receipts, and support visibility.

A useful testing habit is to inspect the Supabase adapter after each synthetic event and verify three things:

• Event persistence, the webhook record exists exactly once.
• State transition, the order moved to the expected status.
• Duplicate safety, replaying the same event doesn't change the result.

Sandbox runs should also cover the customer-facing edge cases that never show up in a clean demo. If you test only approvals, you miss the moments where users abandon the flow, retry from another device, or contact support after a mismatch between the app and the processor. That is where chargeback alerts become useful later, because disputes are easier to handle when your event history is already clean.

If the integration only passes happy-path charges, it isn't ready. Sandbox testing should make the failure modes boring before live users ever see them.

PCI Scope, Local Methods, and Your Go-Live Checklist

The fastest way to stay out of unnecessary PCI scope is to let the gateway SDK tokenize card data instead of collecting raw card numbers yourself. That keeps sensitive data handling inside the provider's flow and out of your Expo app. If you're building a mobile checkout, that's the practical line that keeps the implementation manageable.

Don't ignore regional payment behavior

Card-only checkout works poorly in some markets because it doesn't match how users already pay. Independent market guidance says that in Latin America, Africa, Asia, and MENA, merchants often need local acquiring, local payment methods, and market-specific settlement or compliance support, while generic cross-border card setups can underperform because of higher declines and FX friction (regional payment-method guidance). That's not a theoretical detail, it's a launch decision.

If you're shipping globally from day one, support for wallets, local rails, bank transfers, or vouchers can matter as much as gateway brand choice. The integration model you choose in week one shapes who can complete checkout in month six.

Your go-live board checklist

Use this as the final shipping list:

• Env vars, store publishable keys, secret keys, and webhook secrets separately.
• Hono routes, keep payment creation server-side and small.
• Webhook handler, verify signatures from the raw body and store every event.
• Expo config plugin, wire Apple Pay and Google Pay correctly before release.
• Sandbox suite, test auth, decline, 3-D Secure, refund, void, and timeout paths.
• Live mode toggle, switch only after sandbox assertions pass in the same flow.
• Regional methods, add the payment types that match your target market.

For teams that also want a way to stay ahead of payment disputes and operational noise, chargeback alerts are worth considering as part of the post-launch support stack. They don't fix a broken checkout, but they do help you stay closer to what's happening after the charge lands.

If the app can't explain the payment state from its own database, the integration isn't production-ready yet.

The best version of payment gateway integration in Expo is boring in the right places. The UI feels native, the Hono routes stay small, the webhook handler owns reality, and the test suite proves the ugly cases before users do. If you want a faster path to shipping that kind of stack, visit AppLighter and use it to build the Expo, Hono, and database foundation before you wire in payments, so your first checkout doesn't become your first fire drill.