Webhook - Bemovil

Módulo de Recaudo – Compra de saldo

El módulo de Recaudo en BeMovil permite la integración de múltiples métodos de pago para la compra de saldo adicional, facilitando a los aliados y clientes finales realizar transacciones de manera segura, trazable y en tiempo real.

Cada método de recaudo (Transferencias, PSE, QR estático/dinámico, Nequi, enlaces de pago, entre otros) sigue una estructura unificada de comunicación con la plataforma, garantizando consistencia en la operación, manejo de estados y procesamiento de respuestas.

Uso de confirmUrl (Webhook de confirmación)

Definición

confirmUrl es un endpoint (webhook) proporcionado por el cliente integrador, al cual BeMovil enviará una notificación HTTP POST con el resultado de la transacción una vez que esta haya sido procesada.

Objetivo

Permitir que el sistema del cliente:

Reciba en tiempo real el estado de la transacción.

Actualice su lógica interna (saldo, estados, comprobantes, etc.).

Mantenga sincronización con la plataforma BeMovil.

Autenticación del Webhook

Cada notificación incluye dos headers de seguridad que permiten validar que la solicitud proviene de BeMovil:

Header	Valor	Propósito
`Authorization`	`Bearer {secretKey}`	Token configurado en la plataforma
`X-Signature`	HMAC-SHA256 del payload	Firma para verificar la integridad

¿Cómo se construye la firma?

La firma X-Signature se genera concatenando id, reference y amount separados por punto, firmados con el secretKey:

X-Signature = HMAC-SHA256(secretKey, "{id}.{reference}.{amount}")

El secretKey se configura en la plataforma BeMovil dentro del perfil del negocio. Valida este header antes de procesar cualquier notificación.

Validación — Node.js

Validación — Python

Validación — PHP

Validación — Java

Payload del Webhook

{
  "data": {
    "id": "3141241-123456-123456-AE141232",
    "env": "PROD",
    "Amount": {
      "cost": 500,
      "amount": 50000
    },
    "reference": "REF-001",
    "TransactionStatus": {
      "id": 2,
      "name": "Aprobado"
    },
    "PaymentMethod": {
      "id": 15,
      "name": "Bre-B QR Estático"
    },
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Campo	Tipo	Descripción
`id`	string	UUID de la transacción
`env`	string	`"PROD"` o `"STAGING"`
`Amount.cost`	number	Comisión cobrada por la plataforma
`Amount.amount`	number	Monto de la transacción
`reference`	string	Referencia enviada por el integrador
`TransactionStatus.id`	number	`2` = Aprobado · `3` = Rechazado
`TransactionStatus.name`	string	Nombre legible del estado
`PaymentMethod.id`	number	ID del método de pago utilizado
`PaymentMethod.name`	string	Nombre del método de pago
`createdAt`	string ISO 8601	Fecha y hora de la transacción

Consideraciones importantes

El endpoint confirmUrl debe:

Estar disponible públicamente (HTTPS recomendado).

Responder con 200 OK al recibir la notificación.

Validar X-Signature antes de procesar el payload.

Registrar logs de cada recepción para auditoría.

BeMovil reintenta el envío si el endpoint no responde con 200 OK. El webhook puede llegar segundos o minutos después del pago. Diseña tu endpoint para manejar notificaciones duplicadas de forma idempotente.