Para builders da América Latina
O SaaS boilerplate sério
com MercadoPago nativo
Cobre em reais, pesos ou MXN com MercadoPago embutido — assinaturas recorrentes, webhooks assíncronos assinados e idempotência já resolvidos. Stripe e Polar também estão ligados, pra quando você precisar ir global.
Os kits Stripe-first te deixam colando o MercadoPago na mão
ShipFast, MakerKit e supastarter são Stripe-first. Mas o Stripe não opera direto na Argentina (uma restrição do BCRA), e roteando pela dLocal as taxas reais sobem pra 4-6% e liquidam em contas USD/EUR. Pra cobrar em BRL, ARS ou MXN de forma nativa — com assinaturas recorrentes — o MercadoPago é o trilho pragmático, e muitas vezes o único. Então todo projeto latino termina igual: colando o MercadoPago no Next.js na mão, de novo.
A dor de integrar o MercadoPago, nas palavras dos próprios devs
Obrigados a testar em produção
"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 discussão #62
Desistindo da integração
"I am almost giving up on integrating with Mercado Pago." e "I'm dropping the integration and moving forward with another provider." — Rafael Cardoso e Vicente Martínez, github.com/mercadopago/sdk-js discussão #62
De longe a mais difícil de testar
"de longe essa é a mais complexa e difícil de testar." — rjslegall, github.com/mercadopago/sdk-js discussão #62
MercadoPago, feito do jeito que você faria se tivesse tempo
Assinaturas recorrentes pela API de preapproval. O webhook assíncrono onde a verdade chega depois — assinado e verificado. Handlers idempotentes, pra que uma entrega duplicada nunca cobre duas vezes. É exatamente o encanamento em que quem integra na mão tropeça, ligado atrás de uma interface tipada e coberto por testes. Ligue uma única env var pra escolher. A gente já sofreu isso por você.
1 PAYMENT_PROVIDER=mercado-pago
2 MERCADO_PAGO_ACCESS_TOKEN=...
3 MERCADO_PAGO_WEBHOOK_SECRET=...
4
5 // idempotente sobre externalOrderId — uma
6 // entrega repetida do webhook registra a
7 // compra uma só vez, via outbox durável.
Um contrato de billing, três providers
Troque de provider atrás de uma interface
Stripe, MercadoPago e Polar implementam o mesmo port de payment-provider. Escolha um com uma env var; o resto do seu app não muda.
Todo o ciclo de vida, não o happy path
Checkout, customer portal, mudanças de plano, tratamento de pagamento falho e reconciliação no banco depois do webhook — não uma cobrança avulsa.
Webhooks assinados e idempotentes
Cada provider verifica a assinatura do seu webhook e registra as compras de forma idempotente, então o passo assíncrono onde "a verdade chega depois" nunca cobra duas vezes.
Docs reais em EN, ES e PT — não só locale routing
Locale routing é commodity. Isto é diferente: a própria documentação do produto vem em inglês, espanhol e português como páginas reais de Fumadocs, com inglês como fonte canônica e os siblings ES/PT mantidos em sync. Seu colega que fala português ou espanhol lê o guia de setup no idioma dele, não um machine-translate de última hora.
Tudo o mais que um SaaS de verdade precisa — DDD-layered e testado
Auth
BetterAuth — 2FA, magic-link, OAuth, verificação de email e password reset, já ligados.
Orgs e RBAC
Organizações, membros, convites, permissões por papel e API keys — multi-tenancy de verdade.
Jobs e events
Filas do BullMQ com um dashboard do Bull Board, mais um event bus com outbox durável.
Storage
S3, UploadThing, Supabase ou disco local atrás de um único storage port com keys content-addressed.
Observabilidade
OpenTelemetry, Sentry, Pino e /metrics — cada um um no-op até você configurar.
Faça deploy onde quiser
Docker, Railway ou um VPS puro. Sem lock-in a Stripe nem a um único host.
FAQ do boilerplate com MercadoPago
Ele realmente suporta assinaturas recorrentes do MercadoPago?+
Posso usar Stripe ou Polar em vez do MercadoPago — ou junto?+
Isso é só locale routing com uma etiqueta em português?+
Onde posso fazer deploy?+
Pare de colar o MercadoPago no Next.js na mão.
Comece de uma base onde os reais, o preapproval e o webhook assinado já estão resolvidos — e testados.