Medusa.js

Integra Cost+ con tu tienda Medusa.js v2 usando el plugin oficial costplus-medusa

Integra Cost+ como proveedor de pagos en tu tienda Medusa.js v2. El plugin oficial costplus-medusa registra un proveedor de pagos Medusa separado para cada metodo de pago de Cost+, utiliza el flujo de pagina de pago alojada y verifica cada cambio de estado contra la API de Cost+ — totalmente compatible con PCI DSS.

Requisitos previos

Cuenta de comerciante Cost+ activa
Medusa.js 2.14.2 o posterior
Node.js 22
Acceso a PostgreSQL a traves del DATABASE_URL de Medusa
Una URL de backend Medusa publica HTTPS (requerida para webhooks)
Un checkout de tienda que pase cart_id al iniciar la sesion de pago

Metodos de pago soportados

Nombre en checkout	ID de proveedor Medusa	Identificador Cost+
Credit / Debit Card	`pp_costplus-credit-card_costplus`	`credit-card`
Apple Pay	`pp_costplus-apple-pay_costplus`	`apple-pay`
Google Pay	`pp_costplus-google-pay_costplus`	`google-pay`
Vipps MobilePay	`pp_costplus-vipps-mobilepay_costplus`	`vipps-mobilepay`

Cada proveedor crea un pedido de Cost+ para exactamente un metodo de pago, por lo que las opciones del checkout de la tienda se mantienen alineadas con el flujo de redireccion de pago alojado de Cost+.

1. Instalar el plugin

Instala el paquete en tu proyecto de backend Medusa:

npm install costplus-medusa

Tambien puedes instalar desde una version Git etiquetada: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registrar el plugin y el proveedor

Anade el plugin y el proveedor de pagos a tu medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  plugins: [
    {
      resolve: "costplus-medusa",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "costplus-medusa/providers/costplus",
            id: "costplus",
            options: {},
          },
        ],
      },
    },
  ],
})

Reinicia el backend Medusa para que se carguen el nuevo plugin y el proveedor.

3. Configurar en Admin

En el Medusa Admin, abre Cost+ (ruta /app/costplus) y configura:

API Key — tu clave API de comerciante desde el portal de comerciante (Websites → tu sitio web → Integration)
Expiracion de checkout — tiempo de espera en minutos (enviado a Cost+ como duracion ISO-8601, p. ej. 5 → PT5M, el valor predeterminado es 5 minutos)
Captura manual — opcional, autoriza pagos con tarjeta sin captura inmediata
Registro de depuracion — opcional, registra solicitudes y respuestas de la API para resolver problemas

En la misma página de Admin Cost+, habilita los métodos de pago que quieras exponer para cada región:

Cost+ Credit / Debit Card
Cost+ Apple Pay
Cost+ Google Pay
Cost+ Vipps MobilePay

Solo activa los metodos de pago para los que hayas sido aprobado y hayas recibido confirmacion.

Activar o desactivar metodos en esta pagina actualiza los enlaces de proveedor de pago por region en Medusa para los proveedores de Cost+, por lo que el endpoint estandar del Store API /store/payment-providers?region_id=... devuelve solo los metodos de Cost+ habilitados. Si todos los metodos de Cost+ estan deshabilitados para una region, el Store API no devuelve ningun proveedor de Cost+ para esa region.

4. Integracion de la tienda

Al iniciar una sesion de pago Cost+, pasa el cart_id de Medusa en data:

await sdk.store.payment.initiatePaymentSession(paymentCollection.id, {
  provider_id: "pp_costplus-credit-card_costplus",
  data: {
    cart_id: cart.id,
    return_url: `${origin}/${countryCode}/checkout/costplus/return?cart_id=${cart.id}`,
    failure_url: `${origin}/${countryCode}/checkout?step=payment&costplus_cancelled=1&cart_id=${cart.id}`,
  },
})

Despues de crear la sesion, redirige al comprador a payment_session.data.costplus_payment_url.

La ruta de exito predeterminada es /checkout/costplus/return?cart_id={cart_id} — esa pagina debe llamar al endpoint complete-cart de Medusa y luego mostrar la pagina de confirmacion del pedido. La URL de fallo debe devolver al comprador al paso de pago sin completar el carrito.

El manejo de retorno y webhook siempre verifica el pedido de Cost+ con GET /orders/{id}/ antes de mapear el estado del pago de vuelta a Medusa.

Listar los metodos de pago desde el Store API

Lista los metodos de pago desde el Store API de Medusa en lugar de codificar los IDs de los proveedores de Cost+ directamente en tu tienda. Si la tienda cachea /store/payment-providers, usa no-store o invalida la cache despues de cambios de metodos en Admin para que los metodos deshabilitados desaparezcan del checkout de inmediato.

Para una implementacion de referencia, consulta examples/nextjs/costplus-return/ en el repositorio costplus-medusa — una pagina de retorno del starter DTC de Next.js que combina un handler de cliente con una server action, para que la finalizacion del carrito se ejecute fuera del renderizado y redirija de forma fiable a /order/{id}/confirmed.

5. Webhooks

El plugin registra automaticamente un endpoint de webhook en /hooks/payment/{identifier}_costplus. La URL del backend Medusa debe ser accesible publicamente a traves de HTTPS para que Cost+ pueda entregar actualizaciones de estado asincronas.

Si los pedidos permanecen pendientes mucho tiempo despues de la expiracion configurada, esto apunta a un problema de entrega de webhook o flujo de retorno en lugar de la propia configuracion de expiracion.

6. Seguridad y almacenamiento de configuracion

La clave API se cifra antes de almacenarse en la base de datos de Medusa. Establece COSTPLUS_SETTINGS_SECRET en produccion:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Si no se establece COSTPLUS_SETTINGS_SECRET, el plugin recurre al COOKIE_SECRET o JWT_SECRET de Medusa.

Establece COSTPLUS_API_KEY en el entorno para fijar el origen de la clave API — cuando se establece, la pagina de Admin no la sobrescribira. Dejalo vacio cuando los comerciantes deban gestionar la clave en Admin.

7. Probar y lanzar

El entorno Cost+ se determina por la clave API — una clave de sitio sandbox se ejecuta en modo de prueba, una clave de sitio de produccion se ejecuta en modo en vivo (sin URL de sandbox separada). Realiza algunas transacciones de prueba para verificar los flujos exitosos, cancelados y expirados antes de pasar a produccion.

Soporte

Necesitas ayuda? Contacta con nuestro equipo de soporte en support@costplus.io.

Medusa.js

On this page