P
Pay mpago
MercadoPago payment provider for Medusa v2 — cards with installments, PIX, signed webhooks, provider-initiated refund sync, admin settings UI (pt-BR)
@hewsos/medusa-pay-mpago
MercadoPago (Mercado Pago) payment plugin for Medusa v2
MercadoPago payment provider for Medusa v2 — built for Brazilian stores.
- Credit/debit cards with installments (parcelamento), BIN-based method detection
- PIX with QR code, expiry countdown and a configurable PIX discount promotion
- Signed webhooks (HMAC-SHA256, fail-closed, replay-window checked)
- Provider-initiated refund/chargeback sync — refunds made in the MP dashboard are recorded back into Medusa automatically
- Idempotent (safe under duplicate webhooks and races)
- Admin settings UI (pt-BR): credentials, capture mode, per-method config, connection health checks, order-page live status widget
Install
needs both registrations:
The resulting provider id is and the webhook path segment is — configure in the MercadoPago developers panel. Both strings are public API of this plugin: they are persisted in the database and embedded in webhook URLs. Do not change the after going live.
Instance id convention
The instance encodes the axes along which provider accounts actually vary — not a fixed template:
- MercadoPago accounts vary by brand and country (an MP Brasil seller cannot charge in ARS) → : , , .
- A country-bound carrier (e.g. Correios in ) varies only by brand/contract → alone: . Appending there would encode a dimension with exactly one possible value.
Same rule, applied per provider. Whatever the value: frozen once live.
Host requirements
This plugin reaches into two host-owned resources. Both work out of the box on a standard Medusa installation, but they are requirements your environment must satisfy:
| Requirement | Used for | Notes |
|---|---|---|
| env var | Atomic settings writes ( on Store metadata via a direct connection) | Falls back to read-merge-write through Medusa's ORM if unavailable |
| env var (falls back to ) | AES-256-GCM encryption of stored MP credentials | Rotating the effective key makes stored credentials undecryptable — re-enter them in the admin afterwards |
| PIX discount promotion | The advertised PIX discount is a real server-side promotion | Run once per environment: (the merchant owns the promotion config afterwards) |
Storefront contract
The plugin exposes these Store API routes for a storefront integration (publishable-key scoped):
- — enabled methods, installment config
- — the MP public key for MercadoPago.js
- — PIX payment polling
- — rejection telemetry
- — apply/remove the PIX discount promotion
Removal semantics
The provider is provider-shaped: it defines no data models. Removing the plugin from config flips the row to (Medusa-owned); historical payments keep resolving. The plugin's persistent state lives in Store JSONB keys (, , rejection telemetry) which remain as inert residue after removal.
Supported countries
MercadoPago operates across Latin America and the core of this plugin (Orders API, webhooks, refund sync, credentials) is country-agnostic — but the checkout finish is currently built for Brazil:
| Country | Status | Notes |
|---|---|---|
| 🇧🇷 Brazil | Supported | Cards + installments, PIX (QR/polling/expiry/discount), CPF payer id, pt-BR UI. All testing against MP Brasil. |
| 🇦🇷 🇲🇽 🇺🇾 🇵🇪 Argentina, Mexico, Uruguay, Peru | Planned | Cards should work in principle, but payer identification is hardcoded to CPF (needs DNI/CURP/CI/DNI per country) and UI strings are pt-BR only. Untested. |
| 🇨🇱 🇨🇴 Chile, Colombia | Planned, known blocker | Everything above plus amounts are formatted with 2 decimals — wrong for zero-decimal CLP/COP. Do not use until fixed. |
Known Brazil-isms to generalize before multi-country support: payer identification type (CPF-only today), currency decimal handling (2-decimal assumption), i18n (pt-BR only), per-country payment methods (PIX is Brazil-only; local methods elsewhere are not implemented), semantics assume BRL magnitudes.
Multi-country stores are already modeled by the instance convention (, one provider entry + MP account per country) — the per-country work above is what remains to make non-BR instances real.
Compatibility
| Plugin | Medusa |
|---|---|
| 0.1.x | ^2.13.1 |
Development
If your host app runs in Docker with in a named volume, run the yalc loop inside the container (mount this repo into it) — a host-side will land in a the container never sees.
See DEVELOPMENT.md for the full Docker-host dev loop as actually exercised (yalc paths, compose mount, hot-patch loop, gotchas).
MercadoPago references
This plugin integrates the MercadoPago Orders API () and Payments API. Official documentation (not mirrored here — MP copyright):
- Developers portal: https://www.mercadopago.com.br/developers/pt
- Orders API reference: https://www.mercadopago.com.br/developers/pt/reference/orders/online-payments/create/post
- Webhooks: https://www.mercadopago.com.br/developers/pt/docs/your-integrations/notifications/webhooks
- Test cards & users: https://www.mercadopago.com.br/developers/pt/docs/your-integrations/test/cards
License
MIT © Hewsos