Webhooks

Los webhooks son un mecanismo de las APIs para notificar a sistemas externos de eventos relevantes para tu negocio. En Quentli contamos con distintos eventos a los que puedes suscribirte para enterarte de sucesos importantes. Todos los eventos son enviados con una llamada HTTP POST con un cuerpo JSON.

Eventos disponibles

A continuación se enlistan los eventos que puedes consumir utilizando webhooks.

Puedes desplegar cada evento para ver un ejemplo del cuerpo de la solicitud.

`INVOICE_CREATED`

Enviado cuando se crea una solicitud de pago desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "INVOICE_CREATED",
  "data": {
    "invoiceId": "<id_de_solicitud_de_pago>",
    "amount": 192500,
    "customer": {
      "id": "<id_de_cliente>",
      "customerId": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    },
    "organization": { "id": "<id_de_organización>", "name": "Synergym" },
    "metadata": [
      { "key": "Folio de beca", "value": "012442024" },
      { "key": "Tipo de beca", "value": "Beca Académica 75%" }
    ]
  }
}

`INVOICE_UPDATED`

Enviado cuando se edita una solicitud de pago desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "INVOICE_UPDATED",
  "data": {
    "invoiceId": "<id_de_solicitud_de_pago>",
    "amount": 192500,
    "customer": {
      "id": "<id_de_cliente>",
      "customerId": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    },
    "organization": { "id": "<id_de_organización>", "name": "Synergym" },
    "metadata": [
      { "key": "Folio de beca", "value": "012442024" },
      { "key": "Tipo de beca", "value": "Beca Académica 75%" }
    ]
  }
}

`INVOICE_PAID`

Enviado cuando una solicitud de pago es pagada utilizando un método de pago integrado a Quentli. Las solicitudes pagadas por otros medios no generan este evento.

{
  "eventId": "<id_de_evento>",
  "eventType": "INVOICE_PAID",
  "data": {
    "invoiceId": "<id_de_solicitud_de_pago>",
    "amount": 192500,
    "payment": {
      "id": "<id_de_pago>",
      "amount": 192500,
      "currency": "MXN",
      "paymentTime": "2025-01-20T16:59:16.238Z",
      "monthlyInstallments": null,
      "type": "CARD",
      "cardDetail": {
        "id": "<id_de_tarjeta>",
        "cardholder": "Alejandra Lopez",
        "last4": "3202",
        "brand": "VISA",
        "expiryMonth": 10,
        "expiryYear": 2026,
        "funding": "DEBIT",
        "issuer": "BBVA",
        "country": "MEX"
      }
    },
    "customer": {
      "id": "<id_de_cliente>",
      "customerId": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    },
    "organization": { "id": "<id_de_organización>", "name": "Synergym" },
    "metadata": [
      { "key": "Folio de beca", "value": "012442024" },
      { "key": "Tipo de beca", "value": "Beca Académica 75%" }
    ]
  }
}

`INVOICE_PAID_OTHER`

Enviado cuando una solicitud de pago es pagada utilizando medios externos de pago (e.g., efectivo o terminal bancaria)

{
  "eventId": "<id_de_evento>",
  "eventType": "INVOICE_PAID_OTHER",
  "data": {
    "invoiceId": "<id_de_solicitud_de_pago>",
    "amount": 192500,
    "payment": {
      "id": "<id_de_pago>",
      "amount": 192500,
      "currency": "MXN",
      "paymentTime": "2025-01-20T16:59:16.238Z",
      "monthlyInstallments": null,
      "type": "OTHER",
      "cardDetail": {
        "id": "<id_de_tarjeta>",
        "cardholder": "Alejandra Lopez",
        "last4": "3202",
        "brand": "VISA",
        "expiryMonth": 10,
        "expiryYear": 2026,
        "funding": "DEBIT",
        "issuer": "BBVA",
        "country": "MEX"
      }
    },
    "customer": {
      "id": "<id_de_cliente>",
      "customerId": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    },
    "organization": { "id": "<id_de_organización>", "name": "Synergym" },
    "metadata": [
      { "key": "Folio de beca", "value": "012442024" },
      { "key": "Tipo de beca", "value": "Beca Académica 75%" }
    ]
  }
}

`INVOICE_CANCELED`

Enviado cuando se cancela una solicitud de pago desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "INVOICE_CANCELED",
  "data": {
    "invoiceId": "<id_de_solicitud_de_pago>",
    "amount": 192500,
    "customer": {
      "id": "<id_de_cliente>",
      "customerId": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    },
    "organization": { "id": "<id_de_organización>", "name": "Synergym" },
    "metadata": [
      { "key": "Folio de beca", "value": "012442024" },
      { "key": "Tipo de beca", "value": "Beca Académica 75%" }
    ]
  }
}

`CUSTOMER_CREATED`

Enviado cuando se crea un cliente nuevo desde el Dashboard o la API

{
  "eventId": "<id_del_evento>",
  "eventType": "CUSTOMER_CREATED",
  "data": {
    "customer_id": "<id_del_cliente>",
    "name": "Alicia Ríos",
    "email": "alicia@example.com",
    "phoneNumber": "+523211012928",
    "username": "0000128765"
  }
}

`CUSTOMER_UPDATED`

Enviado cuando se editan los datos de un cliente desde el Dashboard o la API

{
  "eventId": "<id_del_evento>",
  "eventType": "CUSTOMER_UPDATED",
  "data": {
    "customer_id": "<id_del_cliente>",
    "name": "Alicia Ríos",
    "email": "alicia@example.com",
    "phoneNumber": "+523211012928",
    "username": "0000128765"
  }
}

`CUSTOMER_ARCHIVED`

Enviado cuando se archiva un cliente desde el Dashboard o la API

{
  "eventId": "<id_del_evento>",
  "eventType": "CUSTOMER_ARCHIVED",
  "data": {
    "customer_id": "<id_del_cliente>",
    "name": "Alicia Ríos",
    "email": "alicia@example.com",
    "phoneNumber": "+523211012928",
    "username": "0000128765"
  }
}

`PAYMENT_ATTEMPT_SUCCEEDED`

Enviado cuando se hizo un intento de cobro (desde la API, Dashboard o Portal de Clientes) y éste fue exitoso.

{
  "eventId": "we_1234567890",
  "eventType": "PAYMENT_ATTEMPT_FAILED",
  "data": {
    "payment": {
      "id": "p_1234567890",
      "amount": 10000,
      "currency": "MXN",
      "type": "CARD",
      "isCompleted": false
    },
    "paymentAttempt": {
      "id": "pa_1234567890",
      "createdAt": "2025-01-22T18:45:30.796Z",
      "success": true,
      "startedOn": "CUSTOMER_PORTAL",
      "scheduled": false,
      "wasAttemptedByOrganization": false,
      "errorCode": null,
      "attemptNumber": 1
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "aliciarr@ejemplos.com",
      "phoneNumber": "<número_de_celular>",
      "username": "12345",
      "metadata": []
    }
  }
}

`PAYMENT_ATTEMPT_FAILED`

Enviado cuando se hizo un intento de cobro (desde la API, Dashboard o Portal de Clientes) y no fue exitoso.

{
  "eventId": "we_1234567890",
  "eventType": "PAYMENT_ATTEMPT_FAILED",
  "data": {
    "payment": {
      "id": "p_1234567890",
      "amount": 10000,
      "currency": "MXN",
      "type": "CARD",
      "isCompleted": false
    },
    "paymentAttempt": {
      "id": "pa_1234567890",
      "createdAt": "2025-01-22T18:45:30.796Z",
      "success": false,
      "startedOn": "CUSTOMER_PORTAL",
      "scheduled": false,
      "wasAttemptedByOrganization": false,
      "errorCode": "05",
      "attemptNumber": 2
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "aliciarr@ejemplos.com",
      "phoneNumber": "<número_de_celular>",
      "username": "<username_del_cliente>",
      "metadata": []
    }
  }
}

`PAYMENT_COMPLETED`

Enviado cuando se completa un pago exitosamente. Este evento es útil para sistemas que necesitan recibir notificaciones de pagos completados independientemente de si están asociados a una solicitud de pago o no. El arreglo items incluye los conceptos cobrados en el pago. Se construye a partir de los items de las solicitudes de pago relacionadas, los items de la sesión de pago y los items de la orden, de la misma forma que las respuestas de pagos de la API. El arreglo relatedInvoices incluye las solicitudes de pago relacionadas con sus metadatos y sus items con la misma estructura que items.

{
  "eventId": "<id_de_evento>",
  "eventType": "PAYMENT_COMPLETED",
  "data": {
    "paymentSession": {
      "id": "<id_de_sesión>",
      "returnUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "totalAmount": 10000,
      "currency": "MXN",
      "status": "COMPLETED",
      "displayMode": "EMBEDDED",
      "origin": "API",
      "metadata": [
        { "key": "order_id", "value": "ORD-12345" },
        { "key": "campaign", "value": "summer_2025" }
      ]
    },
    "payment": {
      "id": "<id_de_pago>",
      "amount": 10000,
      "currency": "MXN",
      "paymentTime": "2025-02-05T16:30:45.123Z",
      "type": "CARD",
      "authorizationCode": "123456",
      "cardDetail": {
        "id": "<id_de_tarjeta>",
        "cardholder": "Alejandra Lopez",
        "last4": "3202",
        "brand": "VISA",
        "expiryMonth": 10,
        "expiryYear": 2026,
        "funding": "DEBIT",
        "issuer": "BBVA",
        "country": "MEX"
      }
    },
    "items": [
      {
        "description": "Colegiatura Enero 2025",
        "amount": 10000,
        "currency": "MXN",
        "quantity": 1,
        "conceptId": "<id_de_concepto>",
        "concept": {
          "id": "<id_de_concepto>",
          "displayName": "Colegiatura",
          "description": "Colegiatura mensual",
          "amount": 10000,
          "currency": "MXN",
          "groupId": "<id_del_grupo>",
          "group": {
            "id": "<id_del_grupo>",
            "name": "Colegiaturas"
          }
        }
      }
    ],
    "relatedInvoices": [
      {
        "id": "<id_de_solicitud_de_pago>",
        "metadata": [
          { "key": "Folio de beca", "value": "012442024" },
          { "key": "Tipo de beca", "value": "Beca Académica 75%" }
        ],
        "items": [
          {
            "description": "Colegiatura Enero 2025",
            "amount": 10000,
            "currency": "MXN",
            "quantity": 1,
            "conceptId": "<id_de_concepto>",
            "concept": {
              "id": "<id_de_concepto>",
              "displayName": "Colegiatura",
              "description": "Colegiatura mensual",
              "amount": 10000,
              "currency": "MXN",
              "groupId": "<id_del_grupo>",
              "group": {
                "id": "<id_del_grupo>",
                "name": "Colegiaturas"
              }
            }
          }
        ]
      }
    ],
    "paymentAttempt": {
      "id": "pa_1234567890",
      "createdAt": "2025-01-22T18:45:30.796Z",
      "success": true,
      "startedOn": "CUSTOMER_PORTAL",
      "scheduled": false,
      "wasAttemptedByOrganization": false,
      "errorCode": null,
      "attemptNumber": 1
    },
    "customer": {
      "id": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    }
  }
}

Notas importantes:

El campo paymentSession puede ser null si el pago no está asociado a una sesión de pago.
El campo cardDetail puede ser null si el pago no fue realizado con tarjeta (ej. transferencia bancaria, efectivo).
El campo authorizationCode puede ser null dependiendo del procesador de pagos utilizado.

`PAYMENT_REFUNDED`

Enviado cuando se crea un reembolso para un pago desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "PAYMENT_REFUNDED",
  "data": {
    "refund": {
      "id": "<id_de_reembolso>",
      "amount": 10000,
      "currency": "MXN",
      "status": "REQUESTED",
      "createdAt": "2025-01-22T18:45:30.796Z",
      "statusUpdatedAt": "2025-01-22T18:45:30.796Z",
      "customRefundReason": "Solicitud del cliente"
    },
    "payment": {
      "id": "<id_de_pago>",
      "amount": 192500,
      "currency": "MXN",
      "paymentTime": "2025-01-20T16:59:16.238Z",
      "type": "CARD",
      "authorizationCode": "123456",
      "cardDetail": {
        "id": "<id_de_tarjeta>",
        "cardholder": "Alejandra Lopez",
        "last4": "3202",
        "brand": "VISA",
        "expiryMonth": 10,
        "expiryYear": 2026,
        "funding": "DEBIT",
        "issuer": "BBVA",
        "country": "MEX"
      }
    },
    "customer": {
      "id": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ]
    },
    "organization": {
      "id": "<id_de_organización>",
      "name": "Synergym"
    }
  }
}

Nota: El campo status del reembolso puede tener los siguientes valores:

REQUESTED: El reembolso fue solicitado. Dependiendo del procesador, este estatus indica que el reembolso se aprobó.
APPROVED: El reembolso fue aprobado y el cliente debería verlo reflejado en su estado de cuenta
DECLINED: El reembolso fue rechazado por el banco

`PAYMENT_METHOD_CREATED`

Enviado cuando se guarda un método de pago perteneciente a un cliente. Esto puede ser una tarjeta o una cuenta bancaria.

Tarjeta de crédito o débito

{
  "eventId": "<id_del_evento>",
  "eventType": "PAYMENT_METHOD_CREATED",
  "data": {
    "paymentMethod": {
      "id": "<id_del_método_de_pago>",
      "type": "CARD",
      "confirmed": true,
      "chargesConsented": true,
      "cardDetail": {
        "id": "<id_de_tarjeta>",
        "cardholder": "Alejandra Lopez",
        "last4": "3202",
        "brand": "VISA",
        "expiryMonth": 10,
        "expiryYear": 2026,
        "funding": "DEBIT",
        "issuer": "BBVA",
        "country": "MEX"
      }
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "aliciarr@ejemplos.com",
      "phoneNumber": "<número_de_celular>",
      "username": "<username_del_cliente>",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" },
        { "key": "Tipo de beca", "value": "Beca Académica 75%" }
      ]
    }
  }
}

Cuenta bancaria de México (CLABE)

{
  "eventId": "<id_del_evento>",
  "eventType": "PAYMENT_METHOD_CREATED",
  "data": {
    "paymentMethod": {
      "id": "<id_del_método_de_pago>",
      "type": "MEXICAN_BANK_ACCOUNT",
      "confirmed": false,
      "chargesConsented": false,
      "cardDetail": null,
      "bankAccount": {
        "id": "<id_de_cuenta_bancaria>",
        "clabeLast": "8882",
        "clabeFirst": "072",
        "bankCode": "072",
        "bankName": "BANORTE",
        "verified": false
      }
    },
    "customer": {
      "id": "<id_del_cliente>",
      "name": "Alicia Ríos",
      "email": "aliciarr@ejemplos.com",
      "phoneNumber": "<número_de_celular>",
      "username": "<username_del_cliente>",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" },
        { "key": "Tipo de beca", "value": "Beca Académica 75%" }
      ]
    }
  }
}

paymentMethod.chargesConsented será true cuando el usuario haya autorizado cargos automáticos para ese método de pago.

`SUBSCRIPTION_CREATED`

Enviado cuando se crea una suscripción desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "SUBSCRIPTION_CREATED",
  "data": {
    "subscription": {
      "id": "<id_de_suscripción>",
      "description": "Mensualidad Enero 2025",
      "status": "ACTIVE",
      "isActive": true,
      "isCompleted": false,
      "firstCollectionDate": "2025-01-15T00:00:00.000Z",
      "lastCollectionDate": null,
      "nextCollectionDate": "2025-01-15T00:00:00.000Z",
      "numberOfPayments": 12,
      "collectionMethod": "AUTOMATIC",
      "onlyAutomaticCollection": true,
      "items": [
        {
          "description": "Mensualidad",
          "amount": 500000,
          "currency": "MXN",
          "quantity": 1,
          "conceptId": "<id_de_concepto>"
        }
      ]
    },
    "customer": {
      "id": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ],
      "meta": {
        "Nivel": "Ingeniería"
      }
    },
    "organization": {
      "id": "<id_de_organización>",
      "name": "Synergym"
    }
  }
}

`SUBSCRIPTION_UPDATED`

Enviado cuando se actualiza una suscripción desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "SUBSCRIPTION_UPDATED",
  "data": {
    "subscription": {
      "id": "<id_de_suscripción>",
      "description": "Mensualidad Enero 2025",
      "status": "ACTIVE",
      "isActive": true,
      "isCompleted": false,
      "firstCollectionDate": "2025-01-15T00:00:00.000Z",
      "lastCollectionDate": null,
      "nextCollectionDate": "2025-02-15T00:00:00.000Z",
      "numberOfPayments": 12,
      "collectionMethod": "AUTOMATIC",
      "onlyAutomaticCollection": true,
      "items": [
        {
          "description": "Mensualidad",
          "amount": 500000,
          "currency": "MXN",
          "quantity": 1,
          "conceptId": "<id_de_concepto>"
        }
      ]
    },
    "customer": {
      "id": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ],
      "meta": {
        "Nivel": "Ingeniería"
      }
    },
    "organization": {
      "id": "<id_de_organización>",
      "name": "Synergym"
    }
  }
}

`SUBSCRIPTION_CANCELED`

Enviado cuando se cancela una suscripción desde el Dashboard o la API.

{
  "eventId": "<id_de_evento>",
  "eventType": "SUBSCRIPTION_CANCELED",
  "data": {
    "subscription": {
      "id": "<id_de_suscripción>",
      "description": "Mensualidad Enero 2025",
      "status": "CANCELED",
      "isActive": false,
      "isCompleted": false,
      "firstCollectionDate": "2025-01-15T00:00:00.000Z",
      "lastCollectionDate": "2025-06-15T00:00:00.000Z",
      "nextCollectionDate": null,
      "numberOfPayments": 12,
      "collectionMethod": "AUTOMATIC",
      "onlyAutomaticCollection": true,
      "items": [
        {
          "description": "Mensualidad",
          "amount": 500000,
          "currency": "MXN",
          "quantity": 1,
          "conceptId": "<id_de_concepto>"
        }
      ]
    },
    "customer": {
      "id": "<id_de_cliente>",
      "name": "Alicia Ríos",
      "email": "alicia@example.com",
      "phoneNumber": "+528445609708",
      "username": "0000128765",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" }
      ],
      "meta": {
        "Nivel": "Ingeniería"
      }
    },
    "organization": {
      "id": "<id_de_organización>",
      "name": "Synergym"
    }
  }
}

Para configurar los webhooks en tu organización, por favor ponte en contacto con nosotros a través de soporte@quentli.com.

Conceptos

Customers

Catalog

Invoices

Tax Invoices

Subscriptions

Payment Methods

Payments

Payment Sessions

Auth

Webhooks

Eventos disponibles

`INVOICE_CREATED`

`INVOICE_UPDATED`

`INVOICE_PAID`

`INVOICE_PAID_OTHER`

`INVOICE_CANCELED`

`CUSTOMER_CREATED`

`CUSTOMER_UPDATED`

`CUSTOMER_ARCHIVED`

`PAYMENT_ATTEMPT_SUCCEEDED`

`PAYMENT_ATTEMPT_FAILED`

`PAYMENT_COMPLETED`

`PAYMENT_REFUNDED`

`PAYMENT_METHOD_CREATED`

Tarjeta de crédito o débito

Cuenta bancaria de México (CLABE)

`SUBSCRIPTION_CREATED`

`SUBSCRIPTION_UPDATED`

`SUBSCRIPTION_CANCELED`

​Eventos disponibles

​INVOICE_CREATED

​INVOICE_UPDATED

​INVOICE_PAID

​INVOICE_PAID_OTHER

​INVOICE_CANCELED

​CUSTOMER_CREATED

​CUSTOMER_UPDATED

​CUSTOMER_ARCHIVED

​PAYMENT_ATTEMPT_SUCCEEDED

​PAYMENT_ATTEMPT_FAILED

​PAYMENT_COMPLETED

​PAYMENT_REFUNDED

​PAYMENT_METHOD_CREATED

​Tarjeta de crédito o débito

​Cuenta bancaria de México (CLABE)

​SUBSCRIPTION_CREATED

​SUBSCRIPTION_UPDATED

​SUBSCRIPTION_CANCELED

Eventos disponibles

`INVOICE_CREATED`

`INVOICE_UPDATED`

`INVOICE_PAID`

`INVOICE_PAID_OTHER`

`INVOICE_CANCELED`

`CUSTOMER_CREATED`

`CUSTOMER_UPDATED`

`CUSTOMER_ARCHIVED`

`PAYMENT_ATTEMPT_SUCCEEDED`

`PAYMENT_ATTEMPT_FAILED`

`PAYMENT_COMPLETED`

`PAYMENT_REFUNDED`

`PAYMENT_METHOD_CREATED`

Tarjeta de crédito o débito

Cuenta bancaria de México (CLABE)

`SUBSCRIPTION_CREATED`

`SUBSCRIPTION_UPDATED`

`SUBSCRIPTION_CANCELED`