Pay mpago

Name: Pay mpago
Author: Hewsos

Платёжный провайдер MercadoPago для Medusa v2. Карты с рассрочкой, PIX, подписанные вебхуки, синхронизация возвратов со стороны провайдера, интерфейс настроек в Admin (pt-BR)

npm install @hewsos/medusa-pay-mpago

Категория

Платежи

Создано

Hewsos

Версия

0.1.4

Последнее обновление

1 день назад

Ежемесячные загрузки

Звезды на Github

NPM Github

@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

Еще в этой категории

Посмотреть все

Платежи

Braintree

От Lambda Curry

Поддержка платежей и 3D Secure через Braintree

Платежи

Pay.

От Webbers

Принимайте кредитные карты, цифровые платежи и купи сейчас, плати потом

Платежи

Mollie

От Variable Vic

Легко принимайте мультивалютные платежи через Mollie

Плагины

Pay mpago

npm install @hewsos/medusa-pay-mpago

Категория

Платежи

Создано

Hewsos

Версия

0.1.4

Последнее обновление

1 день назад

Ежемесячные загрузки

Звезды на Github

NPM Github

@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

npm install @hewsos/medusa-pay-mpago

needs both registrations:

1module.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 || "",
          },
        },
      ],
    },
  },
],
25})

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

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.

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

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

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).