Webhooks

Los webhooks te permiten suscribirte a los eventos que pueden ocurrir, como que una transacción se apruebe o se rechace. Cuando se dispara un evento, te notificamos a través de un endpoint que hayas configurado previamente, enviando una solicitud POST con un objeto JSON que contiene toda la información necesaria sobre el evento.

Con los webhooks, tu aplicación puede escuchar eventos importantes y disparar acciones, como actualizar la base de datos cuando un pago se procesa correctamente en tu sistema.

INFO

Los webhooks son asíncronos. Las notificaciones se envían normalmente de inmediato, pero pueden producirse retrasos ocasionales. Diseña tu integración para tolerar entregas con retraso o fuera de orden.

Requisitos del endpoint

Antes de configurar un endpoint para recibir notificaciones, este debe cumplir los siguientes requisitos:

Aceptar solicitudes HTTP POST

Tener un certificado SSL válido (HTTPS) y acceso público

Responder con HTTP 200 (OK) en menos de 2 segundos

Aceptar payloads en formato JSON

Tener una URL de no más de 300 caracteres

Tipos de evento

Evento	Descripción
Transacciones aprobadas	Se dispara cuando se aprueba un pago con tarjeta.
Transacciones rechazadas	Se dispara cuando se rechaza un pago con tarjeta.
Reembolsos	Se dispara cuando un reembolso se aprueba, se rechaza o queda pendiente.
Transferencia de fondos a tu cuenta bancaria	Notificación de liquidación SPEI por los fondos transferidos a tu cuenta bancaria.

Según el tipo de evento que dispara la notificación, recibes en el payload un objeto con una estructura determinada.

Para asegurarte de que las solicitudes que llegan a tu endpoint provienen de nosotros, usa las cabeceras X-BP-Signature y X-BP-SignatureKey para autenticar la solicitud entrante. Consulta Seguridad para más detalles.

Registra tu endpoint

Inicia sesión en el dashboard con las credenciales correctas según el ambiente.

Ve a Configuración > Integraciones.

Ingresa la URL de tu endpoint en la sección Webhook General.

Selecciona el tipo de eventos a los que quieres suscribirte.

Haz clic en Guardar.

Nota

El endpoint debe responder con un HTTP Status Code 200 para que se guarde correctamente. Los cambios pueden tardar unos minutos en aplicarse.

Seguridad

Cada notificación POST incluye una firma digital. Los valores de la firma están disponibles en las cabeceras de la solicitud:

Cabecera	Descripción
`X-BP-Signature`	Valor de la firma del payload entregado, codificado en Base64.
`X-BP-SignatureKey`	Índice de la llave privada con la que se firmó el mensaje.

Para obtener la llave pública con la que se verifica la firma, agrega el índice de la llave a la siguiente URL, con la extensión .pem o .der según el formato que prefiera tu aplicación:

https://keys.billpocket.com/webhook/

Ejemplo — para el índice de llave k1:

PEM: https://keys.billpocket.com/webhook/k1.pem

DER: https://keys.billpocket.com/webhook/k1.der

INFO

Te recomendamos guardar en caché o almacenar de algún modo el contenido de la llave pública en tu lado para acelerar la verificación de la firma en las notificaciones siguientes. Las llaves no cambian con el tiempo, pero el índice de la llave puede actualizarse para usar un nuevo par de llaves.

Ejemplos de código

A continuación tienes ejemplos de código para recibir notificaciones de eventos mediante webhooks.

Java

PHP

Node.js

Si usas Spring Boot, obtén los valores de la firma y de la llave de firma para verificar el payload recibido:

El código anterior tiene las siguientes dependencias:

<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.6</version>
</dependency>

<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.54</version>
</dependency>

Transacciones aprobadas

Configura el webhook

Inicia sesión con tu cuenta en el dashboard y selecciona la opción Configuración > Integraciones.

Define la URL de tu webhook en la sección Webhook General y selecciona la opción Transacciones Aprobadas en la pestaña Ventas. Haz clic en Guardar para guardar los cambios.

Nota

Los cambios pueden tardar unos minutos en aplicarse. La URL del webhook no debe superar los 300 caracteres.

Campos del payload

A continuación tienes todas las propiedades que puede contener el payload de un evento de transacción aprobada.

Propiedad	Tipo	Descripción
`result`	String	Resultado de la transacción. Valores posibles: `aprobada` para transacciones aprobadas.
`amount`	String	Monto de la transacción.
`tip`	String	Si la transacción incluye propina, se devuelve.
`payments`	Integer	Si la transacción es diferida, el número de meses de diferido. Por ejemplo, `3`.
`authorizationTime`	String	Hora de autorización. Formato de fecha RFC 3339.
`reference`	String	Descripción de la transacción.
`transactionid`	String	ID de la transacción generado por Kushki.
`authorization`	String	Cadena de autorización de la transacción.
`creditcard`	String	Últimos 4 dígitos del Primary Account Number de la tarjeta.
`cardtype`	String	Emisor de la tarjeta. Valores posibles: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
`arqc`	String	Solo EMV. Authorization Request Cryptogram (ARQC) de la transacción.
`userID`	Integer	ID del usuario que realizó la transacción.
`aid`	String	Solo EMV. Application ID del chip.
`applabel`	String	Solo EMV. Application Label del chip.
`url`	String	Identificador único para acceder al comprobante de la transacción.
`email`	String	Correo al que se envía el comprobante de la transacción.
`phone`	String	Número de teléfono al que se envía el comprobante de la transacción.
`cardBrand`	String	Red del emisor de la tarjeta.
`cardIssuer`	String	Banco emisor de la tarjeta.
`cardCountry`	String	Código de país de la tarjeta (ISO 3166-1 alpha-2).
`cardClass`	String	Tarjeta `DEBIT` (débito) o `CREDIT` (crédito).
`launchTime`	String	Hora en que se envió la transacción.
`maskedPAN`	String	Número de tarjeta enmascarado.
`uniqueReference`	String	Identificador único por transacción generado en tu lado para evitar duplicados. Por ejemplo, un UUID.

Ejemplo

{
    "cardBrand": "MASTERCARD",
    "cardIssuer": "SANTANDER",
    "cardCountry": "MX",
    "cardClass": "CREDIT",
    "launchTime": "2024-05-29T11:01:27.360-0600",
    "userID": 61000,
    "authorizationTime": "2024-05-29T11:01:27.360-0600",
    "result": "aprobada",
    "amount": "100.00",
    "payments": 0,
    "transactionid": "128010",
    "authorization": "BP3500",
    "creditcard": "0009",
    "cardtype": "MASTERCARD",
    "arqc": "A38051D19B2548E3",
    "aid": "A0000000041010",
    "applabel": "Mastercard",
    "url": "face3142cb4d32a545f42d278b8cf4ce5ea3d0b1",
    "maskedPAN": "500000******0009",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407"
}

Transacciones rechazadas

Configura el webhook

Inicia sesión con tu cuenta en el dashboard y selecciona la opción Configuración > Integraciones.

Define la URL de tu webhook en la sección Webhook General y selecciona la opción Transacciones Rechazadas en la pestaña Ventas. Haz clic en Guardar para guardar los cambios.

Nota

Los cambios pueden tardar unos minutos en aplicarse.

Campos del payload

A continuación tienes todas las propiedades que puede contener el payload de un evento de transacción rechazada.

Propiedad	Tipo	Descripción
`result`	String	Resultado de la transacción. Valores posibles: `rechazadaProsa` para transacciones rechazadas.
`amount`	String	Monto de la transacción.
`tip`	String	Si la transacción incluye propina, se devuelve.
`payments`	Integer	Si la transacción es diferida, el número de meses de diferido. Por ejemplo, `3`.
`authorizationTime`	String	Hora de autorización. Formato de fecha RFC 3339.
`reference`	String	Descripción de la transacción.
`transactionid`	String	ID de la transacción generado por Kushki.
`creditcard`	String	Últimos 4 dígitos del Primary Account Number de la tarjeta.
`cardtype`	String	Emisor de la tarjeta. Valores posibles: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
`arqc`	String	Solo EMV. Authorization Request Cryptogram (ARQC) de la transacción.
`userID`	Integer	ID del usuario que realizó la transacción.
`aid`	String	Solo EMV. Application ID del chip.
`applabel`	String	Solo EMV. Application Label del chip.
`cardBrand`	String	Red del emisor de la tarjeta.
`cardIssuer`	String	Banco emisor de la tarjeta.
`cardCountry`	String	Código de país de la tarjeta (ISO 3166-1 alpha-2).
`cardClass`	String	Tarjeta `DEBIT` (débito) o `CREDIT` (crédito).
`launchTime`	String	Hora en que se envió la transacción.
`maskedPAN`	String	Número de tarjeta enmascarado.
`uniqueReference`	String	Identificador único por transacción generado en tu lado para evitar duplicados. Por ejemplo, un UUID.

Nota

A diferencia de las transacciones aprobadas, los rechazos no devuelven authorization, url, email ni phone.

Ejemplo

{
    "cardBrand": "MASTERCARD",
    "cardIssuer": "SANTANDER",
    "cardCountry": "MX",
    "cardClass": "CREDIT",
    "launchTime": "2024-05-29T10:46:52.221-0600",
    "userID": 61000,
    "authorizationTime": "2024-05-29T10:46:52.221-0600",
    "result": "rechazadaProsa",
    "amount": "99.00",
    "payments": 0,
    "transactionid": "128011",
    "creditcard": "0009",
    "cardtype": "MASTERCARD",
    "arqc": "6FEC34124C9AAEEB",
    "aid": "A0000000041010",
    "applabel": "Mastercard",
    "maskedPAN": "500000******0009",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407"
}

Reembolsos

Configura el webhook

Inicia sesión con tu cuenta en el dashboard y selecciona la opción Configuración > Integraciones.

Define la URL de tu webhook en la sección Webhook General y selecciona la opción Transacciones Aprobadas o Transacciones Rechazadas, o ambas, en la pestaña Devoluciones. Haz clic en Guardar para guardar los cambios.

Nota

Los cambios pueden tardar unos minutos en aplicarse.

Campos del payload

A continuación tienes todas las propiedades que puede contener el payload de un evento de reembolso aprobado o rechazado.

Propiedad	Tipo	Descripción
`result`	String	Resultado de la transacción. Valores posibles: `aprobada` para reembolsos aprobados; `rechazadaRiesgo`, `rechazadaProsa` o `rechazada` para reembolsos rechazados; `pendiente` para reembolsos pendientes.
`amount`	String	Monto del reembolso.
`payments`	Integer	Si la transacción es diferida, el número de meses de diferido. Por ejemplo, `3`.
`authorizationTime`	String	Hora de autorización. Formato de fecha RFC 3339.
`transactionid`	String	ID de la transacción generado por Kushki.
`authorization`	String	Cadena de autorización de la transacción. Solo en reembolsos aprobados.
`creditcard`	String	Últimos 4 dígitos del Primary Account Number de la tarjeta.
`cardtype`	String	Emisor de la tarjeta. Valores posibles: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
`userID`	Integer	ID del usuario que realizó la transacción.
`url`	String	Identificador único para acceder al comprobante de la transacción. Solo en reembolsos aprobados.
`cardBrand`	String	Red del emisor de la tarjeta.
`cardCountry`	String	Código de país de la tarjeta (ISO 3166-1 alpha-2).
`cardClass`	String	Tarjeta `DEBIT` (débito) o `CREDIT` (crédito).
`launchTime`	String	Hora en que se envió la solicitud.
`maskedPAN`	String	Número de tarjeta enmascarado.
`uniqueReference`	String	Identificador único por transacción generado en tu lado para evitar duplicados. Por ejemplo, un UUID.
`transactionType`	String	Tipo de transacción. Valores posibles: `devolucion` para reembolsos.
`transactionRefundedId`	String	ID de la transacción original reembolsada.

Ejemplo de reembolso aprobado

{
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardClass": "CREDIT",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407",
    "launchTime": "2024-08-16T10:02:37.965-0600",
    "userID": 61000,
    "authorizationTime": "2024-08-16T10:02:37.965-0600",
    "result": "aprobada",
    "amount": "1018.0",
    "payments": 0,
    "transactionid": "128013",
    "authorization": "BP4160",
    "creditcard": "0002",
    "cardtype": "VISA",
    "url": "19c6f19bc1a7a00a1d76021aa5eaef2627aba950",
    "maskedPAN": "400000******0002",
    "transactionType": "devolucion",
    "transactionRefundedId": "128012"
}

Ejemplo de reembolso rechazado

{
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardClass": "CREDIT",
    "launchTime": "2024-08-15T16:22:52.461-0600",
    "userID": 61000,
    "authorizationTime": "2024-08-15T16:22:52.461-0600",
    "result": "rechazadaProsa",
    "amount": "1003.0",
    "payments": 0,
    "transactionid": "128015",
    "creditcard": "0002",
    "cardtype": "VISA",
    "maskedPAN": "400000******0002",
    "transactionType": "devolucion",
    "transactionRefundedId": "128014"
}

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Requisitos del endpoint#

Tipos de evento#

Registra tu endpoint#

Seguridad#

Ejemplos de código#

Transacciones aprobadas#

Configura el webhook#

Campos del payload#

Ejemplo#

Transacciones rechazadas#

Configura el webhook#

Campos del payload#

Ejemplo#

Reembolsos#

Configura el webhook#

Campos del payload#

Ejemplo de reembolso aprobado#

Ejemplo de reembolso rechazado#

Requisitos del endpoint

Tipos de evento

Registra tu endpoint

Seguridad

Ejemplos de código

Transacciones aprobadas

Configura el webhook

Campos del payload

Ejemplo

Transacciones rechazadas

Configura el webhook

Campos del payload

Ejemplo

Reembolsos

Configura el webhook

Campos del payload

Ejemplo de reembolso aprobado

Ejemplo de reembolso rechazado