Mercadopago

@nicogorga/medusa-payment-mercadopago

Receive payments on your Medusa commerce application using Mercado Pago.

Medusa Payment Mercadopago Repository | Medusa Website | Medusa Repository

[!WARNING] This plugin is a WIP and has only been tested for Credit / Debit Card methods following Mercado Pago docs for Uruguay. You can sumbit issues through GitHub Issues. Feel free to make contributions by making pull requests and proposing ideas / new flows to implement via Discussions

Features

• Mercado Pago integration via Checkout API
• Payments created asynchronously via webhook event.
• Payments automatically captured (so far as for Uruguay, Credit / Debit is auto capture)
• Customers and Cards automatically saved to Mercado Pago, so you can implement saved cards in the frontend

Prerequisites

• Node.js v20 or greater
• A Medusa backend
• For local testing, you need to expose localhost. You can use ngrok
• Mercado Pago developers setup:
  • Mercadopago developer account
  • Mercado Pago Checkout API application
    • Name your app
    • Choose Pagos Online under "Solution Type"
    • Select Yes to ecommerce platform question and select Otrasplataformas from the dropdown
    • Select CheckoutAPI from the "Product to integrate" dropdown
    • Create application. For more information visit Your Integrations
• Setup Mercado Pago (credentials)[https://www.mercadopago.com.uy/developers/es/docs/your-integrations/credentials]:
  • Generate test credentials and optionally, production credentials.
• Setup Mercado Pago webhok notifications
  • Under "Eventos", select Pagos
  • (Optional) Generate a webhook secret. Although it is optional, it is recommended for security purposes.
  • Go to your Medusa backend, run Copy to clipboardyarn dev and in a separate terminal Copy to clipboardngrok http 9000. If you are serving the backend in a port other than 9000, change the last argument accordingly.
    • Your localhost will be exposed by a URL like: Copy to clipboardhttps://d76b-2800-a4-15d2-2900-1105-b8e5-c64-7697.ngrok-free.app.
    • Grab the generated URL and go to Mercado Pago webhook configuration. Under "URL para prueba", specify Copy to clipboard[ngrok URL]/hooks/payment/mercadopago_mercadopago, replaceing Copy to clipboardngrok URL accordingly
• A frontend that integrates Payment brick. I suggest you clone this Storefront

How to Install

1. Run the following command in the directory of the Medusa backend using your package manager (for example for npm):

1
npm install @nicogorga/medusa-payment-mercadopago

2. Set the following environment variables in Copy to clipboard.env:

1234
# Access Token available in your Mercado Pago application Test Credentials section
MERCADOPAGO_ACCESS_TOKEN=
# (Optional) Webhook secret available in your Mercado Pago application Webhooks section
MERCADOPAGO_WEBHOOK_SECRET=

3. In Copy to clipboardmedusa-config.ts add the following at the end of the Copy to clipboardplugins array in your project config object:

123456789101112
projectConfig: {
  plugins = [
  // ...
  {
    resolve: `@nicogorga/medusa-payment-mercadopago`,
    options: {
      accessToken: process.env.MERCADOPAGO_ACCESS_TOKEN,
      webhookSecret: process.env.MERCADOPAGO_WEBHOOK_SECRET,
    },
  },
]
}

4. In Copy to clipboardmedusa-config.ts add the following to the Copy to clipboardmodules array in your project config object:

1234567891011121314151617181920
  modules: [
    {
      resolve: '@medusajs/medusa/payment',
      options: {
        providers: [
          {
            resolve: '@nicogorga/medusa-payment-mercadopago/providers/mercado-pago',
            id: 'mercadopago',
            options: {
              accessToken: process.env.MERCADOPAGO_ACCESS_TOKEN,
              webhookSecret: process.env.MERCADOPAGO_WEBHOOK_SECRET,
            },
            dependencies: [
              ContainerRegistrationKeys.LOGGER
            ]
          }
        ],
      }
    }
  ],

Test the Plugin

1. Run the following command in the directory of the Medusa backend to run the backend:

1
npm run dev

2. Enable Mercadopago in a region in the admin. Alternatively, you can use the Admin APIs.

3. Place an order using a frontend that collects payment data using Mercadopago Payment brick like this. Send a POST to Copy to clipboardlocalhost:9000/store/mercadopago/payment with a body that adheres to validator

Additional Resources

• Mercado Pago Online Payments Docs