Webhooks

Los webhooks entregan notificaciones en tiempo real a su servidor cuando un pago alcanza un estado específico. En lugar de consultar la API en busca de actualizaciones, su sistema recibe una solicitud POST con los detalles del pago.

Eventos soportados

Configuración de webhooks

Los endpoints de webhook se configuran durante el onboarding del comercio. Contacte al equipo de Inyo para:

1. Proporcionar su(s) URL(s) de webhook
2. Seleccionar qué eventos desea recibir
3. Configurar la autenticación (Basic auth o token Bearer)

API de registro de webhooks: Los webhooks también pueden gestionarse de forma programática mediante los endpoints de notificación. Vea la especificación OpenAPI para los endpoints POST, GET y DELETE /notification.

Payload del webhook

Todos los eventos de webhook entregan la misma estructura JSON — el objeto de pago completo en el momento del evento:

{
  "paymentId": "469670e2-31e3-4700-b9f2-abee99418dc4",
  "parentPaymentId": "469670e2-31e3-4700-b9f2-abee99418dc4",
  "externalPaymentId": "order-12345",
  "redirectAcsUrl": "",
  "amount": 95.00,
  "created": "2025-01-21 16:31:02",
  "approved": true,
  "message": "Payment Approved",
  "acquirerMessage": "IN_PROCESS_AUTHORISED",
  "automaticReversed": false,
  "status": "AUTHORIZED",
  "captured": false,
  "voided": false,
  "authCode": "469670e2-31e3-4700-b9f2-abee99418dc4",
  "issuerName": "BANK OF AMERICA",
  "issuerCountry": "UNITED STATES",
  "cvcResult": "NOT_SENT",
  "avsResult": "NOT_SENT",
  "aavAddressResult": "NOT_CHECKED",
  "aavPostcodeResult": "NOT_CHECKED",
  "aavCardholderNameResult": "N/A",
  "aavTelephoneResult": "NOT_CHECKED"
}

Campos del payload

Vea Autorización de un Pago con Tarjeta para una descripción completa de todos los campos de respuesta. El payload del webhook es idéntico al objeto de respuesta del pago.

Manejo de webhooks

Mejores prácticas

1. Devuelva 200 rápidamente — Confirme la recepción antes de realizar procesamiento pesado. Encole el evento para su manejo asíncrono.

2. Verifique el origen — Valide que las solicitudes de webhook provienen del rango de IP de Inyo o verifique las credenciales de autenticación.

3. Maneje los duplicados — Los webhooks pueden entregarse más de una vez. Use paymentId + status como clave de idempotencia.

4. Verifique status, no solo approved — El campo status (AUTHORIZED, CAPTURED, DECLINED, etc.) es el estado autoritativo del pago.

5. No dependa únicamente de los webhooks — Siempre confirme el estado del pago mediante el endpoint GET de pago antes de completar los pedidos. Los webhooks son notificaciones, no la fuente de verdad.

Ejemplo de manejador (Node.js)

app.post('/webhooks/inyo', (req, res) => {
  // Confirmar de inmediato
  res.status(200).send('OK');

  const payment = req.body;
  const { externalPaymentId, status, paymentId } = payment;

  switch (status) {
    case 'AUTHORIZED':
      // Pago autorizado — listo para capturar
      markOrderAsAuthorized(externalPaymentId, paymentId);
      break;
    case 'CAPTURED':
      // Fondos liquidados — completar el pedido
      fulfillOrder(externalPaymentId);
      break;
    case 'DECLINED':
      // Pago fallido — notificar al cliente
      notifyDecline(externalPaymentId, payment.message);
      break;
    case 'VOIDED':
      // Autorización cancelada
      cancelOrder(externalPaymentId);
      break;
    case 'REFUNDED':
      // Fondos devueltos
      processRefund(externalPaymentId, payment.amount);
      break;
  }
});

Política de reintentos

Si su endpoint devuelve una respuesta distinta de 2xx o excede el tiempo de espera, Inyo reintentará la entrega con backoff exponencial. Asegúrese de que su manejador sea idempotente para procesar los reintentos de forma segura.