MercadoPago

@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 Copy to clipboardrefundPayment (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

1
npm install @hewsos/medusa-pay-mpago

Copy to clipboardmedusa-config.ts needs both registrations:

1234567891011121314151617181920
module.exports = defineConfig({
  plugins: [
    { resolve: "@hewsos/medusa-pay-mpago", options: {} },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      key: Modules.PAYMENT,
      options: {
        providers: [
          {
            resolve: "@hewsos/medusa-pay-mpago/providers/mercadopago",
            id: "regia-br", // {brand}-{country} — your instance label
            options: {
              // env fallbacks only — credentials are normally entered in the
              // admin (Settings → MercadoPago → Conexão) and stored encrypted
              accessToken: process.env.MERCADOPAGO_ACCESS_TOKEN || "",
              webhookSecret: process.env.MERCADOPAGO_WEBHOOK_SECRET || "",
            },
          },

The resulting provider id is Copy to clipboardpp_hewsos-mpago_regia-br and the webhook path segment is Copy to clipboardhewsos-mpago_regia-br — configure Copy to clipboardhttps://<your-backend>/hooks/payment/hewsos-mpago_regia-br 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 Copy to clipboardid after going live.

Instance id convention

The instance Copy to clipboardid 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) → Copy to clipboard{brand}-{country}: Copy to clipboardregia-br, Copy to clipboardmri-br, Copy to clipboardregia-ar.
• A country-bound carrier (e.g. Correios in Copy to clipboard@hewsos/medusa-ship-correios) varies only by brand/contract → Copy to clipboard{brand} alone: Copy to clipboardregia. Appending Copy to clipboard-br 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 Copy to clipboardDATABASE_URL env var Atomic settings writes (Copy to clipboardjsonb_set on Store metadata via a direct Copy to clipboardpg connection) Falls back to read-merge-write through Medusa's ORM if unavailable Copy to clipboardMP_ENCRYPTION_KEY env var (falls back to Copy to clipboardJWT_SECRET) 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: Copy to clipboardnpx medusa exec node_modules/@hewsos/medusa-pay-mpago/.medusa/server/src/scripts/create-pix-promotion.js (the merchant owns the promotion config afterwards)

Storefront contract

The plugin exposes these Store API routes for a storefront integration (publishable-key scoped):

• Copy to clipboardGET /store/mercadopago/checkout-config — enabled methods, installment config
• Copy to clipboardGET /store/mercadopago/public-key — the MP public key for MercadoPago.js
• Copy to clipboardGET /store/mercadopago/check-status — PIX payment polling
• Copy to clipboardPOST /store/mercadopago/track-rejection — rejection telemetry
• Copy to clipboardPOST /store/mercadopago/pix-discount — 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 Copy to clipboardpayment_provider row to Copy to clipboardis_enabled = false (Medusa-owned); historical payments keep resolving. The plugin's persistent state lives in Store Copy to clipboardmetadata JSONB keys (Copy to clipboardmercadopago_settings, Copy to clipboardmercadopago_credentials, 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), Copy to clipboardmin_installment_value semantics assume BRL magnitudes.

Multi-country stores are already modeled by the instance Copy to clipboardid convention (Copy to clipboard{brand}-{country}, 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

1234
npm install
npx medusa plugin:build      # compile check
npx medusa plugin:publish    # yalc-publish into a local host app
npx medusa plugin:develop    # watch mode

If your host app runs in Docker with Copy to clipboardnode_modules in a named volume, run the yalc loop inside the container (mount this repo into it) — a host-side Copy to clipboardplugin:add will land in a Copy to clipboardnode_modules 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 (Copy to clipboard/v1/orders) 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