Webhooks - Documentación Quentli

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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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,
      "scheduled": false,
      "wasAttemptedByOrganization": false,
      "errorCode": null,
      "attemptNumber": 1
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "[email protected]",
      "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,
      "scheduled": false,
      "wasAttemptedByOrganization": false,
      "errorCode": "05",
      "attemptNumber": 2
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "[email protected]",
      "phoneNumber": "<número_de_celular>",
      "username": "<username_del_cliente>",
      "metadata": []
    }
  }
}

`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": "[email protected]",
      "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",
      "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": "[email protected]",
      "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,
      "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": "[email protected]",
      "phoneNumber": "<número_de_celular>",
      "username": "<username_del_cliente>",
      "metadata": [
        { "key": "Nivel", "value": "Ingeniería" },
        { "key": "Tipo de beca", "value": "Beca Académica 75%" }
      ]
    }
  }
}

`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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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 [email protected].

Conceptos

​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_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_REFUNDED`

`PAYMENT_METHOD_CREATED`

Tarjeta de crédito o débito

Cuenta bancaria de México (CLABE)

`SUBSCRIPTION_CREATED`

`SUBSCRIPTION_UPDATED`

`SUBSCRIPTION_CANCELED`