Wompi

Name: Wompi
Author: Mantissaio

Wompi El Salvador payment provider plugin for MedusaJS v2

VerifiedVersion 1.1.0 on Medusa 2.22.2, Oct 30, 2026

Featured on Medusa

npm install @mantissaio/medusa-payment-wompi

@mantissaio/medusa-payment-wompi

Leer en Español

Receive payments on your Medusa commerce application using Wompi El Salvador.

Medusa Website | Wompi Docs | Wompi API

Note

This plugin supports the Enlace de Pago (hosted payment page) flow. Tokenization () and recurring payments are not yet supported. The WompiClient includes methods for these endpoints, ready to be wired into the provider in a future release.

Features

Payment via Wompi hosted payment page (Enlace de Pago)
All payment methods supported: credit/debit card, Puntos Agricola, cuotas, Bitcoin, QuickPay, Nequi (opt-in)
Webhook validation via HMAC-SHA256
Auto-capture (Wompi captures at the moment of payment)
Single-use payment links (one successful payment per link)

Prerequisites

Node.js v20+
A Medusa v2 backend (v2.13.0 or later)
A Wompi account with at least one business (negocio) configured
For local testing, expose localhost via ngrok or similar

Wompi credentials

From the Wompi Panel, navigate to your business detail to find:

App ID → used as
API Secret → used as and

Installation

1# npm
2npm install @mantissaio/medusa-payment-wompi
3
4# pnpm
5pnpm add @mantissaio/medusa-payment-wompi
6
7# yarn
8yarn add @mantissaio/medusa-payment-wompi

Configuration

Environment Variables

1WOMPI_CLIENT_ID=<your_app_id>
2WOMPI_CLIENT_SECRET=<your_api_secret>
3WOMPI_API_SECRET=<your_api_secret>

Medusa Configuration

In your :

1module.exports = defineConfig({
// ...
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@mantissaio/medusa-payment-wompi/providers/wompi",
          id: "wompi",
          options: {
            clientId: process.env.WOMPI_CLIENT_ID,
            clientSecret: process.env.WOMPI_CLIENT_SECRET,
            apiSecret: process.env.WOMPI_API_SECRET,
            sandbox: true,
            defaultRedirectUrl: "https://your-store.com/checkout/confirm",
            defaultWebhookUrl: "https://your-store.com/hooks/payment/wompi_wompi",
          },
        },
      ],
    },
  },
],
24});

Options

Option	Required	Description
	Yes	App ID from Wompi panel
	Yes	API Secret for OAuth authentication
	Yes	API Secret for webhook HMAC validation
	No	for development mode (default: )
	No	URL where the customer is redirected after payment
	No	Webhook URL for payment notifications
	No	Override which payment methods are enabled on the payment page

By default, card, Puntos Agricola, cuotas, Bitcoin and QuickPay are enabled. Nequi is opt-in:

1defaultFormaPago: {
permitirTarjetaCreditoDebido: true,
permitirPagoConPuntoAgricola: true,
permitirPagoEnCuotasAgricola: true,
permitirPagoEnBitcoin: true,
permitePagoQuickPay: true,
permitePagoNequi: true,
8},

Webhook Setup

Medusa automatically exposes a webhook endpoint at:

/hooks/payment/wompi_wompi

For local development:

Run your Medusa backend:
In a separate terminal:
Set to

Wompi sends a header (HMAC-SHA256 of the body using your API Secret) which the plugin validates automatically.

Payment Flow

Customer initiates checkout → Medusa calls → plugin creates an Enlace de Pago in Wompi
Storefront calls with → receives
Storefront redirects customer to → customer pays on Wompi's hosted page
Wompi sends webhook to → plugin validates HMAC and confirms payment
Wompi redirects customer to → storefront shows order confirmation

Store API

POST

Request:

{ "paymentSessionId": "ps_01ABC..." }

Response:

1{
2  "urlEnlace": "https://lk.wompi.sv/abc123",
3  "idEnlace": 12345,
4  "urlQrCodeEnlace": "https://wompistorage.blob.core.windows.net/...",
5  "urlEnlaceLargo": "https://wompi.sv/pago/..."
6}

Refunds

Wompi does not expose a refund API. When a refund is issued from the Medusa admin, the plugin records it in Medusa for traceability (with status ) but the actual fund return must be processed manually through the Wompi Panel or directly with Banco Agricola.

Test the Plugin

Run your Medusa backend:
Enable Wompi in a region via the admin dashboard or Admin API
Make sure your business is in development mode in the Wompi panel (transactions won't be real)
To simulate a rejected payment in development mode, use CVV

Development

1# Install dependencies
2pnpm install
3
4# Run tests
5pnpm test
6
7# Build
8pnpm build
9
10# Dev mode (watch)
11pnpm dev

Local testing with a Medusa project

1# From your Medusa project directory
2pnpm add ../path-to/medusa-payment-wompi

Additional Resources

Similar plugins

View all

Payments

Mercadopago

By Nicolas Gorga

Accept payments across Latin America

Featured on Medusa

Payments

Pay mpago

By Hewsos

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

Featured on Medusa

Payments

Sumup

By Meister-eder

SumUp payment provider for Medusa v2

Featured on Medusa