Consideraciones

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.

El webhook incluirá datos como:

  "data": {
    "id": "string",
    "Amount": {
      "cost": "number",
      "amount": "number"
    },
    "reference": "string",
    "TransactionStatus": {
      "id": "string | number",
      "name": "string"
    },
    "PaymentMethod": {
      "id": "string | number",
      "name": "string"
    },
    "createdAt": "string (ISO 8601 datetime)"
  }
}

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.