Integration Module 2.0 for Medusa is outRead the announcement
Pay mpago logo

Pay mpago

MercadoPago payment provider for Medusa v2 — cards with installments, PIX, signed webhooks, provider-initiated refund sync, admin settings UI (pt-BR)

npm install @hewsos/medusa-pay-mpago
Category
Built by
Version
0.1.4
Last updated
2 months ago
Monthly downloads
Loading downloads

@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:

RequirementUsed forNotes
env varAtomic 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 credentialsRotating the effective key makes stored credentials undecryptable — re-enter them in the admin afterwards
PIX discount promotionThe advertised PIX discount is a real server-side promotionRun 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:

CountryStatusNotes
🇧🇷 BrazilSupportedCards + installments, PIX (QR/polling/expiry/discount), CPF payer id, pt-BR UI. All testing against MP Brasil.
🇦🇷 🇲🇽 🇺🇾 🇵🇪 Argentina, Mexico, Uruguay, PeruPlannedCards 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, ColombiaPlanned, known blockerEverything 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

PluginMedusa
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):

License

MIT © Hewsos