Configurar Webhooks y notificaciones

Debido a que las interacciones con los terminales físicos requieren tiempo (p. ej., esperar a que se introduzca un PIN), Get Smart API Cloud devuelve el resultado final de una transacción de forma asíncrona.

Para recibir este resultado, debes exponer un endpoint HTTP público (Webhook) en tu servidor. API Cloud enviará una petición POST a esta URL que contendrá los detalles finales de la transacción, los códigos de autorización y los datos del recibo.

Configuración

Defines dónde enviar la notificación por petición. Esto significa que puedes enrutar diferentes transacciones a diferentes endpoints si es necesario.

En cada llamada a la API (Pago, Devolución, Preautorización), incluye el objeto notificacion:

{
  "info": {
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payments",
      "correoNotificacion": "admin@merchant.com"
    },
    ...
  }
}

• urlNotificacion: El canal principal. Debe ser una URL HTTPS accesible públicamente.
• correoNotificacion: El canal de respaldo. Si tu servidor está inactivo o devuelve un error (distinto de 200), el sistema enviará el resultado por correo electrónico a esta dirección.

El payload de notificación

Cuando el terminal termina de procesar, tu servidor recibirá un payload JSON.

Método: POST

Content-Type: application/json

Ejemplo de payload

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timeStamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1",
      "Literales": {
         "autenticadoPorPin": "OPERACION CON PIN. FIRMA NO NECESARIA."
      }
    }
  },
  "signature": "INCOMING_SERVER_SIGNATURE"
}

Campos clave a procesar

Securizar su Webhook

Dado que la URL de tu webhook es pública, cualquiera podría, en teoría, enviarte peticiones falsas. Debes verificar la firma de cada notificación entrante.

Pasos de verificación

1. Capturar el cuerpo en bruto (Raw Body): Lee el cuerpo JSON entrante.
2. Extraer info: Separa el objeto info de la signature.
3. Calcular el hash: * Minimiza la cadena JSON de info (elimina los espacios en blanco).
   • Añade tu clave del comercio.
   • Calcula el SHA256.
4. Comparar: Comprueba si tu hash calculado coincide con la signature del payload.

Advertencia de seguridad: Si las firmas no coinciden, descarta la petición inmediatamente. No actualices el estado de tu pedido ni entregues los bienes.

Mejores prácticas

1. Idempotencia

Los reintentos de red pueden provocar que reciba la misma notificación dos veces. Asegúrate de que tu sistema pueda gestionar peticiones duplicadas para la misma factura (ID de factura) sin cobrar al cliente dos veces o corromper tu base de datos.

2. Acuse de recibo rápido

Tu servidor debe devolver un estado 200 OK inmediatamente después de recibir y almacenar los datos del webhook. Si tarda demasiado en responder, API Cloud podría considerar que la entrega ha fallado y activar el respaldo por correo electrónico.

3. Gestionar respaldos

Si recibes una notificación por correo electrónico (porque tu servidor estaba inactivo), contendrá los mismos datos en un formato legible por humanos. Es posible que necesites un proceso manual para actualizar los pedidos en función de estos correos electrónicos si tu sistema automatizado falla.

Solución de problemas

Próximos pasos

• Consultar el historial de transacciones: Si se ha perdido un webhook, utiliza el endpoint Query (Consulta) para recuperar el estado manualmente.
• Especificaciones de impresión de recibos: Aprende a formatear los datos de Literales y datosDCC en tickets impresos.