Webhook de pago recibido

Vendis enviará una notificación asíncrona a tu sistema cada vez que un cliente realice el pago de un QR generado. Para ello debes proporcionar a Vendis la URL (Endpoint) de tu sistema.

Especificación de la Notificación

• Ruta: <URL_DEL_SISTEMA_INTEGRADOR> (Ej. api/v2/simple-qrs/callback)
• Método: POST
• Reintentos: El sistema realizará hasta 3 reintentos si tu servidor no responde con un estado de éxito (HTTP 200 OK).

Seguridad y Cabeceras (Headers - Requerido)

Para garantizar que cada notificación recibida en tu servidor provenga legítimamente de los servidores de Vendis (validando el origen y evitando suplantaciones de identidad), Vendis exige el uso de autenticación mediante Bearer Token.

Al configurar la URL de tu Webhook en el panel de administración de Vendis, se te proveerá un Secreto del Webhook único. Vendis incluirá este secreto de forma obligatoria en el encabezado Authorization de cada petición HTTP.

• Header: Authorization
• Formato: Bearer <SECRETO_DEL_WEBHOOK>
• Ejemplo: Authorization: Bearer sec_webhook_8a7d9f...

aviso

Tu servidor debe validar obligatoriamente la presencia de este encabezado y comprobar que coincida exactamente con tu secreto configurado. Si la cabecera no está presente o no es idéntica, tu sistema debe responder inmediatamente con un código HTTP 401 Unauthorized y abortar el procesamiento de la transacción.

Payload (Datos enviados por Vendis)

El sistema de Vendis enviará un payload JSON con los detalles del pago:

{
  "payment_date": "2023-02-03 09:09:02",
  "payment_amount": "34.00",
  "qr_id": "234234",
  "payment_name": "Carlos Vargas",
  "payment_bank": "Bisa",
  "status": "PAID"
}

Respuesta Esperada

Tu sistema debe responder a la petición confirmando la recepción para detener el ciclo de reintentos de Vendis.

Respuesta de Éxito de tu Sistema (HTTP 200 OK)

{
    "message": "Ok"
}

Respuesta de Error de tu Sistema (HTTP 400 Bad Request / 500 Internal Server Error)

{
  "type": "api_error",
  "code": "invalid_request",
  "message": "Mensaje de error descriptivo"
}

Nota: Esperamos que tu sistema responda siguiendo las buenas prácticas de la industria con códigos de error representativos, pero principalmente el webhook se reintentará o marcará como fallido basado en el Status Code devuelto por tu servidor.