For LATAM builders
The serious SaaS boilerplate
with native MercadoPago
Charge in pesos, reais, or MXN with MercadoPago built in — recurring subscriptions, signed async webhooks, and idempotency already solved. Stripe and Polar are wired too, for when you need to go global.
Stripe-first kits leave you gluing MercadoPago by hand
ShipFast, MakerKit, and supastarter are Stripe-first. But Stripe doesn't operate directly in Argentina (a BCRA restriction), and routing through dLocal pushes real fees to 4-6% and settles to USD/EUR accounts. To charge in ARS, BRL, or MXN natively — with recurring subscriptions — MercadoPago is the pragmatic, and often the only, rail. So every LATAM project ends the same way: gluing MercadoPago into Next.js by hand, again.
The MercadoPago integration pain, in developers' own words
Forced to test in production
"Please fix the sandbox for the Checkout Pro; it's just plainly unacceptable that we need to test our integration in production." — Víctor G. G. Quiroga, github.com/mercadopago/sdk-js discussion #62
Giving up on the integration
"I am almost giving up on integrating with Mercado Pago." — Rafael Cardoso, and "I'm dropping the integration and moving forward with another provider." — Vicente Martínez, github.com/mercadopago/sdk-js discussion #62
The hardest one to test
"de longe essa é a mais complexa e difícil de testar" (by far the most complex and hardest to test). — rjslegall, github.com/mercadopago/sdk-js discussion #62
MercadoPago, done the way you would if you had the time
Recurring subscriptions through the preapproval API. The async webhook where the truth lands later — signed and verified. Idempotent handlers, so a duplicated delivery never double-charges. It is the exact plumbing DIY integrators trip on, wired behind a typed interface and covered by tests. Flip a single env var to select it.
1 PAYMENT_PROVIDER=mercado-pago
2 MERCADO_PAGO_ACCESS_TOKEN=...
3 MERCADO_PAGO_WEBHOOK_SECRET=...
4
5 // idempotent on externalOrderId — a repeat
6 // webhook delivery records the purchase once,
7 // through a durable outbox event bus.
One billing contract, three providers
Swap providers behind one interface
Stripe, MercadoPago, and Polar implement the same payment-provider port. Pick one with an env var; the rest of your app never changes.
The whole lifecycle, not the happy path
Checkout, customer portal, plan changes, failed-payment handling, and DB reconciliation after the webhook — not just a one-off charge.
Signed, idempotent webhooks
Each provider verifies its webhook signature and records purchases idempotently, so the async "truth lands later" step can never charge twice.
Real docs in EN, ES, and PT — not just locale routing
Locale routing is a commodity. This is different: the product documentation itself ships in English, Spanish, and Portuguese as real Fumadocs pages, with English as the canonical source and ES/PT siblings kept in sync. Your Spanish- or Portuguese-speaking teammate reads the setup guide in their language, not a machine-translated afterthought.
Everything else a real SaaS needs — DDD-layered and tested
Auth
BetterAuth — 2FA, magic-link, OAuth, email verification, and password reset, already wired.
Orgs & RBAC
Organizations, members, invitations, role-based permissions, and API keys — real multi-tenancy.
Jobs & events
BullMQ queues with a Bull Board dashboard, plus a durable outbox event bus.
Storage
S3, UploadThing, Supabase, or local disk behind one storage port with content-addressed keys.
Observability
OpenTelemetry, Sentry, Pino, and /metrics — each a no-op until you configure it.
Deploy anywhere
Docker, Railway, or a plain VPS. No Stripe-only or single-host lock-in.
MercadoPago boilerplate FAQ
Does it really support MercadoPago recurring subscriptions?+
Can I use Stripe or Polar instead — or as well?+
Is this just i18n routing with a Spanish label?+
Where can I deploy it?+
Stop gluing MercadoPago into Next.js by hand.
Start from a base where the pesos, the preapproval, and the signed webhook are already solved — and tested.