Commerce & payments

Astropress supports two headless commerce engines and one payment router. These are independent: you can use a commerce engine without HyperSwitch, HyperSwitch without a commerce engine, or all three together.

Commerce engines

A commerce engine gives you a product catalogue, cart, orders, and a checkout flow. Both options are MIT-licensed and self-hosted.

Medusa

Medusa is a modular headless commerce platform. Its plugin ecosystem and API surface are deliberately close to Shopify’s — teams migrating from Shopify will find the concepts familiar.

Attribute	Detail
Licence	MIT
Hosting	Node.js server (persistent — not edge/static compatible)
Language	TypeScript
API	REST + Events
Ecosystem	Large plugin registry (payment providers, fulfilment, analytics)

astropress new my-site --commerce medusa
astropress add --commerce medusa   # existing project

After scaffolding, see medusa-config.js and the Medusa quickstart guide.

When it’s the right choice: you want a battle-tested commerce backend with a large plugin ecosystem and Shopify-compatible concepts. Good for teams already familiar with Shopify’s data model.

Limitations:

• Requires a persistent Node.js server — not compatible with static hosts or edge runtimes
• Medusa v2 is a significant rewrite from v1; check the migration guide before upgrading

Further reading: docs.medusajs.com

Vendure

Vendure is a TypeScript-native headless commerce framework built around a GraphQL API. It is more developer-ergonomic than Medusa for teams comfortable with TypeScript and GraphQL.

Attribute	Detail
Licence	MIT
Hosting	Node.js server (persistent — not edge/static compatible)
Language	TypeScript
API	GraphQL + REST
Ecosystem	Plugin system via NestJS modules

astropress new my-site --commerce vendure
astropress add --commerce vendure

When it’s the right choice: you prefer a GraphQL API, are comfortable with NestJS conventions, or find Medusa’s REST-first approach awkward. Vendure’s type safety extends from the server to your storefront queries.

Limitations:

• Requires a persistent Node.js server
• Steeper learning curve if you’re not familiar with NestJS
• Smaller plugin ecosystem than Medusa

Further reading: docs.vendure.io

Payments: HyperSwitch

HyperSwitch is an open-source payment router made by Juspay (India). Instead of integrating directly with one payment provider, you integrate with HyperSwitch once and route to 50+ providers through a single API. It includes a pre-built Unified Checkout Web SDK that renders the right payment UI automatically.

Attribute	Detail
Router licence	Apache 2.0
Web SDK licence	MIT
Hosting	Self-hosted Rust server (or HyperSwitch cloud)
Made by	Juspay — India’s largest payment infrastructure company

astropress new my-site --payments hyperswitch
astropress add --payments hyperswitch

Scaffolding writes env stubs and generates src/components/HyperCheckout.astro — a complete checkout form that auto-selects the right UI based on which connectors you enable.

Regional payment support

Region	Provider	Methods
East Africa	Safaricom M-Pesa / Daraja	STK Push: phone number → PIN prompt on device, no redirect
West & Southern Africa	Flutterwave (NG, GH, ZA, TZ, UG + 20 more)	Mobile money (MTN, Airtel), USSD, bank transfer, cards
West & Southern Africa	Paystack (NG, GH, KE, ZA)	Cards, bank transfer, USSD, mobile money
India	Razorpay	UPI, IMPS, NEFT, cards, netbanking
India	Cashfree	UPI, UPI QR, cards, wallets
India	PayU	UPI, EMI, cards, wallets
India	PhonePe	UPI via PhonePe switch
Southeast Asia	Xendit (PH, ID)	GCash, Maya (PH) · OVO, GoPay, QRIS, bank VA (ID)
Southeast Asia	Adyen (SG, MY, TH, VN, PH, ID)	GrabPay, PayNow (SG), PromptPay (TH), FPX/DuitNow (MY), QRIS (ID)
Middle East & N. Africa	Noon (AE, SA, EG, JO)	Cards, mada (SA), Meeza (EG)
Middle East & N. Africa	Checkout.com (AE, SA, KW, QA, BH, EG)	mada (SA), KNET (KW), BENEFIT (BH), Fawry (EG), cards
Latin America	dLocal (BR, MX, AR, CL, CO, PE + 9 more)	PIX (BR), OXXO (MX), Boleto (BR), PSE (CO), bank transfer, cards
Latin America	Ebanx (BR, MX, CO, AR, CL, PE)	PIX (BR), Boleto (BR), OXXO (MX), cards
Latin America	PayU (BR, CO, PE)	PIX (BR), PSE (CO), Efecty (CO), cards
Global	Stripe	Cards, Apple Pay, Google Pay
Global	Adyen	Cards + all regional methods above
Global	PayPal	PayPal, Venmo
Global	Checkout.com	Cards, Apple Pay, digital wallets

Configure connectors via the HyperSwitch dashboard after deploying — no code changes required to add or swap providers.

How the checkout works

HyperCheckout.astro loads the HyperSwitch Web SDK (MIT, juspay/hyperswitch-web) and mounts a Unified Checkout element. The SDK inspects which connectors are active and the user’s device, then renders:

• M-Pesa / mobile money: phone-number field → STK Push (Safaricom) or mobile money prompt (Flutterwave/Paystack)
• UPI: VPA (UPI ID) field + collect flow — Razorpay, Cashfree, PayU, PhonePe
• GrabPay / PromptPay / PIX / OXXO: redirect or in-page QR based on provider
• Cards / Apple Pay / Google Pay: standard card form or native payment sheet

The component is wired to HYPERSWITCH_PUBLISHABLE_KEY (client-side) and expects a client_secret you create server-side using HYPERSWITCH_API_KEY. See the component comments for a minimal API route example.

When it’s the right choice:

• You need M-Pesa, mobile money, UPI, PIX, or other local methods alongside cards
• You want to switch or add providers via a dashboard without touching code
• You want a fallback connector if your primary provider has an outage
• You’re building for East Africa, West Africa, India, Southeast Asia, MENA, LatAm, or a multi-region audience

Using HyperSwitch without a commerce engine: it works standalone for one-time payments, donations, or ticket sales.

Further reading: hyperswitch.io/docs · Web SDK

Putting it together

A typical commerce setup:

# Commerce engine + payment router
astropress new my-site --commerce medusa --payments hyperswitch

# Payments only (no product catalogue — suitable for donations, tickets)
astropress new my-site --payments hyperswitch

Both Medusa and Vendure have native payment provider plugins. If you use them alongside HyperSwitch, configure HyperSwitch as the payment provider in the commerce engine’s settings.