@quadcore-lib/payments-mercadopago

PaymentProvider de @quadcore-lib/payments-server sobre MercadoPago Checkout Pro (preferencias + webhooks v2).

Instalación

npm install @quadcore-lib/payments-mercadopago

Uso

import { QuadcorePaymentsModule } from '@quadcore-lib/payments-server';
import { MercadoPagoProvider } from '@quadcore-lib/payments-mercadopago';

QuadcorePaymentsModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (config: ConfigService) =>
    new MercadoPagoProvider({
      accessToken: config.get('MP_ACCESS_TOKEN'),
      webhookSecret: config.get('MP_WEBHOOK_SECRET'),
      backUrls: {
        success: 'https://mitienda.com/checkout/success',
        failure: 'https://mitienda.com/checkout/failure',
        pending: 'https://mitienda.com/checkout/pending',
      },
      notificationUrl: 'https://api.mitienda.com/payments/webhook',
    }),
});

Cómo funciona

• createPayment: crea una preferencia de Checkout Pro (POST /checkout/preferences) — no un pago; MercadoPago recién genera el pago real cuando el cliente completa el checkout. Devuelve providerPaymentId = id de la preferencia y redirectUrl = init_point (a dónde mandar al cliente).
• verifyWebhook: valida la firma x-signature (ts=...,v1=...) más x-request-id, con el manifest id:{data.id};request-id:{x-request-id};ts:{ts}; firmado HMAC-SHA256 contra webhookSecret — algoritmo de Webhooks v2 de MercadoPago. Si la firma es válida, consulta GET /v1/payments/{data.id} para confirmar el pago y obtener external_reference (el orderId que se mandó al crear la preferencia).

El id del webhook no es el id de la preferencia

El pago real que llega por webhook tiene un id distinto al de la preferencia creada en el checkout — son dos recursos distintos de la API de MercadoPago. Por eso este provider siempre manda orderId en el WebhookResult (vía external_reference): PaymentsService.handleWebhook (en payments-server) ya contempla esto — si no encuentra el pago por providerPaymentId, busca por orderId y adopta el id nuevo para los próximos webhooks del mismo pago.

Mapeo de estados

| Estado de MercadoPago | PaymentStatus | |---|---| | approved | approved | | refunded, charged_back | refunded | | rejected, cancelled | rejected | | cualquier otro (pending, in_process, authorized, ...) | pending |

⚠️ Sin probar contra un sandbox real

Esta implementación sigue la documentación pública de MercadoPago (Checkout Pro + Webhooks v2) al momento de escribirse, pero no se probó contra una cuenta de MercadoPago real en esta sesión. Antes de producción: verificar el formato exacto del manifest firmado y la respuesta de /v1/payments/:id contra un webhook real (sandbox de MercadoPago), especialmente si usás topic/IPN v1 en vez de webhooks v2.

API

| Export | Descripción | |---|---| | MercadoPagoProvider | Implementa PaymentProvider (createPayment, verifyWebhook). | | MercadoPagoProviderOptions | accessToken, webhookSecret (requeridos); backUrls?, notificationUrl?, apiBaseUrl? (opcionales, este último para tests/sandbox). |

Requisitos

• @quadcore-lib/payments-server (trae la interfaz PaymentProvider y el módulo que consume este provider).
• @nestjs/common >=10 (peer).
• rawBody: true en bootstrapQuadcoreApp (ya es el default) — la firma se valida sobre el body crudo.
• Access token y webhook secret de una cuenta de MercadoPago (panel de desarrolladores → Tus integraciones → Webhooks).