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)

Como parte del flujo de integración, se introduce el campo confirmUrl, el cual cumple un rol crítico dentro del proceso:

Definición

confirmUrl es un endpoint (webhook) proporcionado por el cliente integrador, al cual BeMovil enviará una notificación HTTP 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.

Funcionamiento

Si el campo confirmUrl está presente en la transacción:

BeMovil realizará una petición HTTP (generalmente POST) hacia dicha URL.

Se enviará un payload estructurado con la información relevante de la transacción.

Autenticación del Webhook
En el encabezado (header) del webhook se incluirá un token de autorización, el cual deberá ser previamente configurado en la plataforma. Este token es esencial para garantizar la seguridad, ya que permite validar que las solicitudes recibidas provienen de una fuente confiable. De esta manera, se evita que la URL del webhook quede expuesta a peticiones no autorizadas o abiertas. Es responsabilidad del cliente configurar correctamente este token y validarlo en su endpoint antes de procesar cualquier solicitud.

El webhook incluirá datos como:

  {
  "data": {
    "id": "string", // UUID de la transacción. Ej: "3141241-123456-123456-AE141232"
    "Amount": {
      "cost": "number", // Costo de servicio/comisión cobrado por la plataforma
      "amount": "number" // Monto neto recibido (en centavos)
    },
    "reference": "string", // Referencia interna del pago generada por la plataforma
    "TransactionStatus": {
      "id": "string | number", // ID del estado. Ej: 2
      "name": "string" // Nombre del estado. Ej: "Aprobado", "Rechazado"
    },
    "PaymentMethod": {
      "id": "string | number", // ID del método de pago usado
      "name": "string" // Nombre del método. Ej: "Bre-B QR", "PSE"
    },
    "createdAt": "string (ISO 8601 datetime)", // Fecha y hora del pago. Ej: "2024-01-15T10:30:00Z"
    "Order": {
      "id": "string", // UUID interno de la orden en el sistema
      "code": "string", // Código de la planilla asociada. Ej: "PL-123"
      "description": "string" // Descripción de la planilla al momento del pago
    }
  }
}

Consideraciones importantes

El endpoint (confirmUrl) debe:

Estar disponible públicamente (HTTPS recomendado).

Ser capaz de recibir y procesar solicitudes HTTP de forma segura.

Responder con códigos HTTP adecuados (200 OK esperado).

Logs de recepción para auditoría.