Skip to content

Webhooks

Descripción

MetrePay envía notificaciones automáticas (callbacks) ante ciertos eventos relevantes, como confirmaciones de pago o finalización de suscripciones. Estas notificaciones permiten mantener actualizados los estados de cuenta de los clientes en el sistema del comercio.

Configuración

La configuración de webhooks se realiza a través del portal web del comercio, en el menú Configuración / Notificaciones. Se pueden dar de alta nuevos eventos y modificar los existentes de forma autogestionada.

Eventos Configurables

Evento Significado
PAYMENT_SUCCESS Pago exitoso
SUBSCRIPTION_FINALIZED Débito automático finalizado

Parámetros Requeridos

Parámetro Descripción
Evento PAYMENT_SUCCESS o SUBSCRIPTION_FINALIZED
Callback URL URL del endpoint destinado a recibir las notificaciones
Método HTTP POST, PUT o PATCH

Parámetros Opcionales

Parámetros relacionados con capas de seguridad adicionales. Se pueden usar en conjunto o de forma independiente.

Parámetro Descripción
Header Key + Header Value Tupla de autenticación por header (se soporta hasta una tupla)
Basic Auth User + Basic Auth Password Credenciales de autenticación básica

Estructura de la Notificación de Pago

Ejemplo Estándar

{
  "event": "PAYMENT_SUCCESS",
  "data": {
    "txId": "30370",
    "payRequestId": 988,
    "currency": "PYG",
    "amount": "80000.00",
    "statusId": 200,
    "customIdentifier": "123123",
    "customIdentifier2": "456456",
    "label": "Cuota Social - Plan A",
    "email": "juanperez@mail.com",
    "name": "Juan Pérez"
  }
}

Ejemplo con Campos de Conciliación

Para los comercios con el parámetro "Realiza sus propias conciliaciones" activado, se incluyen dos campos adicionales dentro de data:

{
  "event": "PAYMENT_SUCCESS",
  "data": {
    "txId": "30370",
    "payRequestId": 988,
    "currency": "PYG",
    "amount": "80000.00",
    "processor": "PARAGUAY.BANCARD",
    "payment_method": "DEBIT_CARD",
    "statusId": 200,
    "customIdentifier": "123123",
    "customIdentifier2": "456456",
    "label": "Cuota Social - Plan A",
    "email": "juanperez@mail.com",
    "name": "Juan Pérez"
  }
}

Campos de la Notificación

Campo Descripción
payRequestId Número de ticket MP que se visualiza en el portal. Puede usarse como referencia de comprobante de pago.
currency Moneda del pago.
amount Monto del pago. Incluye siempre dos decimales.
customIdentifier Identificador personalizado establecido por el comercio (ej: número de cédula, número de socio, código de póliza).
customIdentifier2 Segundo identificador personalizado establecido por el comercio (ej: número de contrato, número de abono).
label Concepto del pago.
email Correo utilizado en la generación del link del cliente. No confundir con el email de catastro de tarjetas. Se incluye para registros y notificaciones del comercio.
name Nombre del cliente utilizado en la generación del link. Se incluye para registros y notificaciones del comercio.

Campos Adicionales de Conciliación

Estos campos se incluyen solo para comercios con el parámetro de conciliaciones activado.

Campo Descripción Valores Posibles
processor Procesadora de origen de la transacción. "PARAGUAY.BANCARD", "PARAGUAY.BEPSA"
payment_method Tipo de tarjeta utilizada en la transacción. "CREDIT_CARD", "DEBIT_CARD"

Notas

  • El campo payment_method está disponible para pagos por suscripción (tarjetas tokenizadas). Para pagos únicos, el processor se envía correctamente pero el tipo de tarjeta puede no estar disponible dependiendo de la procesadora.
  • Si el comercio no tiene activado el parámetro de conciliaciones, los campos processor y payment_method no se incluyen en la notificación.