Плагины Medusa
M

Mercadopago medusa plugin

A starter for Medusa plugins.

Нужна доработка этого плагина?

Связаться с нами
npm install @qbk/mercadopago-medusa-plugin
Категория
other
Создано
qbk
Тип
unknown
Последнее обновление
1 месяц назад
Ежемесячные загрузки
29

🧩 @qbk/mercadopago-medusa-plugin

A MedusaJS plugin to integrate Mercado Pago as a payment provider.

It supports credit/debit card payments, ticket payments, and allows you to save and list customer cards for future purchases.

📘 Useful Resources

MedusaJS Official Documentation

Mercado Pago API

Mercado Pago Node.js SDK

Compatibility

RequisitoVersión mínima
MedusaJS
Node.js
Mercado Pago SDK

💳 Features

✅ Credit and debit card payments

✅ Ticket payments (e.g., Pago Fácil, Rapipago)

✅ Payment authorization and capture (manual or automatic)

✅ Save customer cards for future purchases

✅ List saved cards

✅ Automatic payment status updates via webhooks

✅ Full integration with MedusaJS payment flow

🧠 Usage

Once configured, Medusa will recognize Mercado Pago as an available payment provider. You can create payments from your Storefront or Admin using the corresponding provider_id:

pp_credit_mercadopago

pp_debit_mercadopago

pp_ticket_mercadopago

🔔 Webhooks

The plugin automatically handles notifications (notification_url) sent by Mercado Pago. Ensure your MEDUSA_BACKEND_URL points to /hooks/payment/provider_id.

🚀 Instalación

npm install @qbk/mercadopago-medusa-plugin
# o
yarn add @qbk/mercadopago-medusa-plugin

Configure the plugin in medusa.config.ts:

[Modules.PAYMENT]: {
resolve: "@medusajs/medusa/payment",
options: {
providers: [
{
resolve: "@qbk/mercadopago-medusa-plugin/providers/mercadopago",
id: "mercadopago",
options: {
accessToken: process.env.MP_ACCESS_TOKEN,
capturePayment: process.env.MP_CAPTURE_PAYMENT,
backendUrl: process.env.MEDUSA_BACKEND_URL
},
},
],
},
},

Environment Variables

To run this project, you will need to add the following environment variables to your .env file

ParameterDescription
accessToken mercadopago
true o false
backendUrl

Tech Stack

Client: React, TailwindCSS

Server: Node, Express, Next js

Framework Medusa

License

MIT

Contributing

Maintained by: Javier Sosa & MedusaJS LATAM Community

👨‍💻 Autors

🚀 About Me

I'm a full stack developer...

Store

Retrieve customer saved payment methods:

Storefront

Add the following attributes when querying cards:

Helper function to fetch saved payment methods:

Steps in the storefront to make a payment with Mercado Pago

Once you have selected the payment provider in the checkout and completed all the card details — or chosen a ticket option — you need to start the payment session by calling the initiatePaymentSession method

In the data parameter, you must include all the information required by Mercado Pago to create a payment.

PropertyTypeDescription
Main payment body containing Mercado Pago form data.
Optional Mercado Pago payment ID if it already exists.
Session identifier from the payment flow.
Indicates if the card should be saved for future use.
URL provided by Mercado Pago for redirection or resource access.
Information about the cardholder or account holder.
Extra metadata for card saving and holder reference.
├─ Indicates if the card should be saved.
├─ Indicates if the payment uses a saved card.
└─ Optional ID of the associated account holder.

MpAccountHolder

PropertyTypeDescription
Name of the cardholder.
Last four digits of the card.
Payment entity or processor.
Masked digits to display (e.g., ).
Type of payment (e.g., , ).
Number of installments.
Collection center or origin of payment.

MpPaymentBody

PropertyTypeDescription
Optional external reference (usually the order ID).
Mercado Pago payment method details.
Card issuer ID.
(+)Includes standard Mercado Pago card form data.
(+)Includes saved card payer data.
(+)Includes ticket-based payment data (for cash or voucher payments).
(+)Additional Mercado Pago form information.

Components

🧩 CardSelector

React component to list and select saved cards, generate secure tokens, and fetch available installments (for credit cards).

This component exposes a method that can be invoked through its reference, which returns…

💳 CardSelectorRef

PropertyTypeDescription
Asynchronous function that handles the card selection form submission. Returns a promise that resolves with the generated card token, the selected saved card (if any), and the selected installment option. Returns if the submission fails or is cancelled.

🧩 Returned Object

PropertyTypeDescription
Token generated by Mercado Pago for the selected card.
The saved card used for the payment, if applicable.
The selected installment plan, including number of payments and interest details.

MpCardForm Component

💳 MpCardProps

PropertyTypeDescription
The payment method selected by the user (e.g., , ).
The total amount to be charged in the transaction.
The current shopping cart object containing products, quantities, and totals.
Locale configuration for Mercado Pago, used to adapt language and formatting.

💳 MpCardRef

PropertyTypeDescription
Asynchronous method exposed by the component reference. It can be invoked to submit the card payment form and returns a promise that resolves with the created payment data (), or / if the submission fails or is canceled.

Implement

🎟️ MpTicketForm Component

A React component that renders a Mercado Pago Ticket payment form (cash or voucher-based payments). It uses the @mercadopago/sdk-react library and exposes a method via ref to programmatically submit the payment form

🚀 Features

Integrates Mercado Pago's Ticket Payment Brick.

Automatically initializes Mercado Pago with your public key.

Supports localized configuration via MpLocale.

Exposes a ref method (mpTicketHandleSubmit) to handle form submission and obtain payment data.

Can be easily used inside a checkout flow (e.g. in Medusa.js storefronts).

⚙️ Props

PropertyTypeDescription
The selected payment provider. The component renders only if the value equals .
The total transaction amount.
The current shopping cart containing user and order data (used for the payer’s email).
Mercado Pago locale (e.g. , , ).

🌎 MpLocale

LocaleDescription
Spanish (Argentina)
Spanish (Chile)
Spanish (Colombia)
Spanish (Mexico)
Spanish (Venezuela)
Spanish (Uruguay)
Spanish (Peru)
Portuguese (Brazil)
English (United States)

🔄 Returned Object — MpCreatePayment

PropertyTypeDescription
Payment form data returned by the Mercado Pago SDK.
Mercado Pago payment ID (null for new payments).
Contains details about the payment method and type.
├─ The payment collection method (e.g., ).
└─ The payment type returned by Mercado Pago.

🧠 Internal Logic

Initializes Mercado Pago using initMercadoPago(publicKey, { locale }).

Renders a component configured for ticket payments.

Hides default UI elements (button, title, redirection panel).

Exposes mpTicketHandleSubmit, which:

Calls paymentBrickController.getFormData() to get the form data.

Builds and returns an MpCreatePayment object.

⚠️ Environment Variables

You must define your Mercado Pago public key in your environment:

Medusa - Mercadopago medusa plugin