Recibe eventos de Bold a través de webhook
El webhook de Bold te permite conectar tus sistemas para recibir automáticamente notificaciones sobre eventos de pagos y transacciones.
Estas notificaciones informarán a tus sistemas sobre los eventos que ocurren en las transacciones realizadas a través de los métodos de pago utilizados en Bold como: pagos con datáfonos, links de pago o botones de pago.
¿Para qué usar un webhook?
Los webhooks de Bold te permiten recibir notificaciones inmediatas sobre el estado de las transacciones de pago en tus sistemas backend. Esto te facilitará tomar acciones rápidas y automáticas en tu comercio.
Para recibir las notificaciones, debes configurar un endpoint HTTP de tipo POST
. Cuando ocurra un evento, Bold realizará una solicitud al mismo e incluirá los detalles del evento en el cuerpo de la solicitud.
¿Qué tipo de eventos puedo recibir?
Puedes recibir los siguientes eventos relacionados con el flujo de pagos:
- Venta aprobada
- Venta rechazada
- Anulación aprobada
- Anulación rechazada
¿Cómo lo integro?
Para comenzar a recibir eventos en tu aplicación debes añadir un webhook dentro del Panel de Comercios en la sección de Integraciones.
Para hacerlo, sigue los siguientes pasos:
-
Crea un endpoint para recibir las peticiones
POST
con la información de los eventos -
Registra el endpoint dentro del Panel de Comercios en la sección de Integraciones
-
Verifica el origen de los eventos recibidos
Próximamente podrás configurar los diferentes tipos de eventos que desees recibir en los puntos de conexión configurados.
Crea el endpoint
Debes crear un endpoint que pueda aceptar peticiones HTTPS de tipo POST
.
Este endpoint debe:
- Recibir la solicitud
POST
con un cuerpo en formato JSON como el del siguiente ejemplo:
{
"id": "191850cb-00f8-4f64-aa5f-4975848e9428",
"type": "SALE_REJECTED",
"subject": "CP332C3C9WZU",
"source": "/payments",
"spec_version": "1.0",
"time": 1711989345347444700,
"data": {
"payment_id": "CP332C3C9WZU",
"merchant_id": "CKKA859CGE",
"created_at": "2024-04-01T11:35:42-05:00",
"amount": {
"total": 111111,
"taxes": [
{
"base": 96618,
"type": "VAT",
"value": 4831
}
],
"tip": 9662
},
"card": {
"capture_mode": "CHIP",
"franchise": "VISA",
"cardholder_name": "DARIO SUAREZ RUBEN",
"terminal_id": "qpos_mini_27000230021050800072"
},
"user_id": "b7221e5b-aa8a-4c13-8105-8771a0088d35",
"payment_method": "CARD",
"metadata": {
"reference": null
}
},
"datacontenttype": "application/json"
}
- El endpoint debe responder inmediatamente con el código de estado 200 antes de que cualquier lógica de tu sistema provoque un error por tiempo de espera (con un máximo de 2 segundos permitidos). Esta respuesta confirma que el evento fue recibido correctamente.
A continuación encontrarás la descripción de cada uno de los campos contenidos en el cuerpo del JSON.
Descripción de estructura de la notificación
Nombre del campo | Descripción |
---|---|
id | UUID de la notificación. Es única para cada notificación enviada. |
type | Tipo de la notificación. Describe el estado de transacción al momento de emitir la notificación. Sus posibles valores son: SALE_APPROVED → “Venta aprobada” SALE_REJECTED → “Venta rechazada” VOID_APPROVED → “Anulación aprobada” VOID_REJECTED → “Anulación rechazada” |
subject | ID de la transacción que está siendo notificada. Este ID es definido por Bold. |
source | Recurso que lanzó la notificación en cuestión. |
spec_version | Versión de la especificación CloudEvents (opens in a new tab) usada. |
time | Hora de emisión de la notificación en formato POSIX. |
data | Cuerpo de la notificación. Iincluye información de la transacción tal como: fecha de creación, monto, impuestos, método de pago, información del método de pago, referencia externa enviada a Bold al momento del pago, etc. |
datacontenttype | Formato en el que se encuentra el body de la notificación. |
Descripción del cuerpo de la notificación
Campo | Tipo | Descripción |
---|---|---|
payment_id | string | ID de la transacción generado por Bold. Permite llevar trazabilidad de la misma. |
merchant_id | string | ID del comercio que está haciendo la transacción. |
created_at | string | Cadena de texto que contiene la fecha y hora de creación de la transacción en formato ISO 8601 con time zone América/Bogotá. |
amount | object | Contiene información detallada de los montos a procesar. Incluye el monto total, los impuestos asociados y la propina correspondiente. |
amount.total | number | Cantidad correspondiente al total a procesar en la transacción. Incluye propinas e impuestos asociados. |
amount.taxes | List[Object] | Lista de objetos que contienen todos los impuestos asociados a la transacción en cuestión. Cada objeto incluye el tipo del impuesto, la base y el valor del mismo. |
amount.tip | number | Cantidad correspondiente a la propina asignada a la transacción. |
card | object | Información básica de la tarjeta con la que se realizó el pago. |
card.capture_mode | string | Método de captura usado para el pago. |
card.franchise | string | Franquicia de la tarjeta usada en el pago. Los posibles valores son: VISA VISA_ELECTRON MASTERCARD MAESTRO AMERICAN_EXPRESS CODENSA DINERS DISCOVER TUYA SODEXO OLIMPICA UNKOWN |
card.cardholder_name | string | Nombre del tarjetahabiente. |
card.terminal_id | string | ID del datáfono usado para la captura de la tarjeta. |
user_id | string | ID del usuario del comercio que inició la transacción. |
payment_method | string | Método de pago usado en la transacción. Los posibles valores son: CARD → tarjetas de crédito/débito SOFT_POS → tarjetas de crédito/débito usando el dispositivo móvil CARD_WEB → tarjetas de crédito/débito usando link de pago PSE → pago por PSE DAVIPLATA → Pago por Daviplata NEQUI → pago por nequi BOTON_BANCOLOMBIA → pago por Botón Bancolombia |
metadata.reference | string | Referencia de pago enviada mediante el uso del deeplink por el comercio. Es retornado tal cual se envía al deeplink al momento de hacer una transacción. |
Registra el endpoint
Después de crear el endpoint, registra la URL en la sección de Integraciones en el Panel de Comercios para que Bold sepa a dónde enviar los eventos.
Formato de la URL del webhook
El formato de la URL para registrar tu webhook es el siguiente:
https://<tu-website>/<tu-webhook-url>
Para registrar tu webhook debes:
-
Ve a la sección Integraciones en el Panel de Comercios. Si ingresas por primera vez debes activar las llaves de integración con el botón Activar llaves.
Entre las llaves generadas encontratás la llave secreta. Esta sirve para verificar la autenticidad de la información enviada a la URL del webhook.
-
Luego de activar las llaves, ve a la sección Webhooks y haz clic en el botón Configurar webhook.
-
Agrega la URL del webhook en el campo URL de punto de conexión y haz clic en Crear webhook.
-
Ahora verás la URL que acabas de configurar en la sección de webhooks creados y podrás empezar a recibir automáticamente eventos de webhook cada vez que se realice una transacción.
-
Para dejar de recibir notificaciones en tu webhook configurado, simplemente elimínalo de tu lista de webhooks utilizando el botón de la papelera () ubicado en el lado derecho de la URL.
Las notificaciones de ventas realizadas mediante:
- Datáfono Bold Plus
- Link de pagos
- Botón de pagos
- Versiones antiguas de la app Bold
pueden tener una demora de máximo 10 minutos para que sean notificadas a tu webhook. Estamos trabajando para que estos tiempos sean menores.
Verifica el origen de los eventos recibidos
Te recomendamos asegurar tu integración de webhook con Bold. Para ello, es importante verificar que todas las peticiones realizadas a la URL del webhook sean generadas exclusivamente por Bold.
Cómo verificar las firmas de webhook
Para asegurar que la información provenga de Bold y garantizar la integridad de los datos, puedes seguir estos pasos:
-
Convertir el cuerpo recibido a formato Base64.
-
Cifrar el cuerpo en Base64 utilizando la llave secreta con el algoritmo de encriptación HMAC-SHA256 para generar un HMAC (código de autenticación de mensajes) en formato hexadecimal.
-
Comparar el resultado obtenido con el valor del encabezado x-bold-signature incluido en la petición y verificar que sean idénticos.
Ejemplo del contenido enviado en el header x-bold-signature
'x-bold-signature': '381db35c39c6e3016884c70054ade14f4d78bcd8167e8d1170751fe3bce74662'
A continuación encuentras un snippet que puedes utilizar para hacer la verificación de la firma:
from flask import Flask, request
import hmac
import hashlib
import base64
app = Flask(**name**, instance_relative_config=False)
@app.route("/", methods=["POST"])
def validate_signature():
signature = request.headers.get("x-bold-Signature", "")
body = request.get_data(parse_form_data=False)
str_message = body.decode(encoding="utf-8")
encoded = base64.b64encode(str_message.encode("utf-8"))
hashed = hmac.new(key="<secret_key>".encode(), digestmod=hashlib.sha256, msg=encoded).hexdigest()
is_valid_request = hmac.compare_digest(hashed.encode(), signature.encode())
if is_valid_request:
# 200 response and process event
pass
else:
# 400 status_code
pass