Webhooks

Los webhooks notifican a tu servidor cuando ocurre un evento relevante en Quentli. Cada entrega es una solicitud HTTP POST con un cuerpo JSON UTF-8 y el siguiente sobre:

{
  "eventId": "wev_1234567890",
  "eventType": "PAYMENT_ATTEMPT_SUCCEEDED",
  "data": {}
}

eventId identifica una entrega. Guarda y deduplica este valor: el mismo evento se puede entregar más de una vez.

Configura un webhook

Crea un endpoint HTTPS desde POST /v1/webhooks. Define solamente los eventos que tu integración procesa.

POST /v1/webhooks

{
  "input": {
    "url": "https://miapp.com/webhooks/quentli",
    "description": "Sincronización de cobros",
    "enabledEvents": ["INVOICE_PAID", "PAYMENT_ATTEMPT_SUCCEEDED", "PAYMENT_ATTEMPT_FAILED"]
  }
}

Entrega y reintentos

Responde 2xx en menos de 10 segundos para confirmar la entrega.
Las respuestas no 2xx, timeouts y errores de conexión se reintentan hasta ocho veces, después del primer intento.
Los reintentos se programan después de 2 segundos, 10 segundos, 5 minutos, 20 minutos, 1 hora, 5 horas, 1 día y 3 días.
No asumas orden entre eventos. Usa eventId para deduplicar y consulta el estado actual del recurso si recibes eventos fuera de orden.
Puedes consultar el historial en GET /v1/webhook-events y reintentar una entrega con POST /v1/webhook-events/{id}/retry.

Eventos disponibles

Evento	Se envía cuando
`INVOICE_CREATED`	Se crea una solicitud de pago.
`INVOICE_UPDATED`	Se actualiza una solicitud de pago.
`INVOICE_CANCELED`	Se cancela una solicitud de pago.
`INVOICE_PAID`	Se liquida una solicitud mediante Quentli o su total es cero.
`INVOICE_PAID_OTHER`	Se registra un pago recibido fuera de Quentli.
`CUSTOMER_CREATED`	Se crea un cliente.
`CUSTOMER_UPDATED`	Se actualiza un cliente.
`CUSTOMER_ARCHIVED`	Se archiva un cliente.
`PAYMENT_ATTEMPT_SUCCEEDED`	Un intento de cobro termina correctamente.
`PAYMENT_ATTEMPT_FAILED`	Un intento de cobro es rechazado o falla.
`PAYMENT_COMPLETED`	Un pago termina de procesarse.
`PAYMENT_METHOD_CREATED`	Un cliente guarda un método de pago.
`PAYMENT_REFUNDED`	Se actualiza un reembolso de un pago.
`DISPUTE_CREATED`	Se crea un contracargo.
`DISPUTE_RESPONSE_CREATED`	Se registra una respuesta a un contracargo.
`DISPUTE_RESOLVED`	Se resuelve un contracargo.
`SUBSCRIPTION_CREATED`	Se crea una suscripción.
`SUBSCRIPTION_UPDATED`	Se actualiza una suscripción.
`SUBSCRIPTION_CANCELED`	Se cancela una suscripción.

Estructura de `data`

Los payloads incluyen todos los campos descritos a continuación. Los objetos y campos marcados como opcionales pueden ser null o no estar presentes según el evento y el método de pago.

Eventos	Campos principales de `data`
Facturas	`invoiceId`, `description`, `amount`, `invoice`, `payment?`, `customer?`, `organization`, `metadata`, `formAnswers?`
Clientes	`id`, `name`, `email`, `phoneNumber`, `username`, `metadata`
Intentos de pago	`payment`, `paymentAttempt`, `customer`, `paymentSession`
Pago completado	`payment`, `items`, `relatedInvoices`, `paymentAttempt?`, `customer`, `paymentSession?`
Método de pago	`paymentMethod`, `customer`
Reembolsos	`refund`, `payment`, `customer`, `organization`
Contracargos	`dispute`, `response`, `payment`, `customer`, `organization`
Suscripciones	`subscription`, `customer`, `organization`

Facturas

invoice contiene id, amount, currency, dueDate, expireDate e items. Cada item incluye description, amount, currency, quantity y conceptId. Cuando existe un pago, payment incluye su identificador, monto, moneda, fecha de pago, tipo, código de autorización y detalles de tarjeta cuando corresponde.

Intentos y pagos

Los eventos de intento incluyen payment.status, payment.isCompleted, payment.meta y paymentAttempt con id, createdAt, success, startedOn, automatic, scheduled, wasAttemptedByOrganization, attemptNumber, errorCode, errorType y errorResponse. Los detalles de tarjeta y la sesión de pago pueden ser null. PAYMENT_COMPLETED incluye los items cobrados y las facturas relacionadas. Su paymentAttempt es null cuando no existe un intento asociado.

Métodos de pago

paymentMethod contiene id, type, confirmed, chargesConsented, cardDetail y bankAccount. Los detalles de tarjeta o cuenta bancaria son null cuando no aplican. customer incluye sus identificadores, datos de contacto y metadatos.

Suscripciones, reembolsos y contracargos

Las suscripciones contienen sus fechas de cobro, estado, método de cobranza, items y el cliente asociado. Los reembolsos incluyen su estado, monto, fechas y pago original. Los contracargos incluyen estado, motivo, fecha límite de respuesta, respuesta asociada y pago original.

Ejemplo: método de pago creado

{
  "eventId": "wev_1234567890",
  "eventType": "PAYMENT_METHOD_CREATED",
  "data": {
    "paymentMethod": {
      "id": "pm_1234567890",
      "type": "CARD",
      "confirmed": true,
      "chargesConsented": true,
      "cardDetail": {
        "id": "card_1234567890",
        "cardholder": "Ana Rodriguez",
        "last4": "4242",
        "brand": "VISA",
        "expiryMonth": 12,
        "expiryYear": 2028,
        "funding": "DEBIT",
        "issuer": "BBVA",
        "country": "MEX"
      },
      "bankAccount": null
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Ana Rodriguez",
      "email": "ana@example.com",
      "phoneNumber": "+525555123456",
      "username": "cliente-123",
      "metadata": [],
      "meta": {}
    }
  }
}

Conceptos

Guías

Endpoints

Schemas

Configura un webhook

Entrega y reintentos

Eventos disponibles

Estructura de `data`

Facturas

Intentos y pagos

Métodos de pago

Suscripciones, reembolsos y contracargos

Ejemplo: método de pago creado

​Configura un webhook

​Entrega y reintentos

​Eventos disponibles

​Estructura de data

​Facturas

​Intentos y pagos

​Métodos de pago

​Suscripciones, reembolsos y contracargos

​Ejemplo: método de pago creado

Configura un webhook

Entrega y reintentos

Eventos disponibles

Estructura de `data`

Facturas

Intentos y pagos

Métodos de pago

Suscripciones, reembolsos y contracargos

Ejemplo: método de pago creado