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 (Copy to clipboardsavePaymentMethod) 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
• 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
• 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 Copy to clipboardWOMPI_CLIENT_ID
• API Secret → used as Copy to clipboardWOMPI_CLIENT_SECRET and Copy to clipboardWOMPI_API_SECRET

Installation

12345678
# npm
npm install @mantissaio/medusa-payment-wompi

# pnpm
pnpm add @mantissaio/medusa-payment-wompi

# yarn
yarn add @mantissaio/medusa-payment-wompi

Configuration

Environment Variables

123
WOMPI_CLIENT_ID=<your_app_id>
WOMPI_CLIENT_SECRET=<your_api_secret>
WOMPI_API_SECRET=<your_api_secret>

Medusa Configuration

In your Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
module.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",
            },
          },
        ],

Options

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

Webhook Setup

Medusa automatically exposes a webhook endpoint at:

1
/hooks/payment/wompi_wompi

For local development:

1. Run your Medusa backend: Copy to clipboardpnpm dev
2. In a separate terminal: Copy to clipboardngrok http 9000
3. Set Copy to clipboarddefaultWebhookUrl to Copy to clipboardhttps://<ngrok-url>/hooks/payment/wompi_wompi

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

Payment Flow

1. Customer initiates checkout → Medusa calls Copy to clipboardinitiatePayment() → plugin creates an Enlace de Pago in Wompi
2. Storefront calls Copy to clipboardPOST /store/wompi/payment-link with Copy to clipboard{ paymentSessionId } → receives Copy to clipboard{ urlEnlace }
3. Storefront redirects customer to Copy to clipboardurlEnlace → customer pays on Wompi's hosted page
4. Wompi sends webhook to Copy to clipboard/hooks/payment/wompi_wompi → plugin validates HMAC and confirms payment
5. Wompi redirects customer to Copy to clipboarddefaultRedirectUrl → storefront shows order confirmation

Store API

POST Copy to clipboard/store/wompi/payment-link

Request:

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

Response:

123456
{
  "urlEnlace": "https://lk.wompi.sv/abc123",
  "idEnlace": 12345,
  "urlQrCodeEnlace": "https://wompistorage.blob.core.windows.net/...",
  "urlEnlaceLargo": "https://wompi.sv/pago/..."
}

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 Copy to clipboardpending_manual) but the actual fund return must be processed manually through the Wompi Panel or directly with Banco Agricola.

Test the Plugin

1. Run your Medusa backend: Copy to clipboardpnpm dev
2. Enable Wompi in a region via the admin dashboard or Admin API
3. Make sure your business is in development mode in the Wompi panel (transactions won't be real)
4. To simulate a rejected payment in development mode, use CVV Copy to clipboard111

Development

1234567891011
# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

# Dev mode (watch)
pnpm dev

Local testing with a Medusa project

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

Additional Resources

• Wompi API Documentation
• Wompi Swagger
• Wompi Panel
• Medusa Payment Module Docs