Recibe eventos de Bold a través de tu endpoint 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 a tu endpoint e incluirá los detalles del evento en el cuerpo de la solicitud.
¿Qué tipos 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 de webhook en tu aplicación, debes crear un webhook dentro del panel de Comercios en la sección de Integraciones (opens in a new tab).
Para hacerlo, sigue los pasos a continuación:
-
Crea un punto de conexión para recibir las peticiones POST con la información de los eventos
-
Registra el punto de conexión dentro del panel de comercios en la sección de integraciones
-
Asegura tu integración webhook
Puedes registrar desde uno (1) y hasta cinco (5) puntos de conexión.
Próximamente podrás configurar los diferentes tipos de eventos que desees recibir en los puntos de conexión configurados
Crea el punto de conexión
Debes crear un punto de conexión HTTPS que pueda aceptar peticiones POST de webhook.
Este punto de conexión debe:
- Recibir la solicitud POST con un cuerpo JSON como el 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 punto de conexión debe responder inmediatamente con el código de estado 200 antes de que cualquier lógica de tu sistema provoque un error de 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 estructura 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 usado que lanzó la notificación en cuestión |
spec_version | Versión de la especificación cloudevents usada |
time | Hora de emisión de la notificación en formato POSIX |
data | Cuerpo de la notificación, incluye 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 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 TX con nosotros |
merchant_id | string | Id del comercio que está haciendo la TX |
created_at | string | Cadena de texto que contiene la fecha y hora de creación de la TX 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 TX, incluye propinas e impuestos asociados |
amount.taxes | List[Object] | Lista de objetos que contienen todos los impuestos asociados a la TX 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 TX |
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 TX |
payment_method | string | Método de pago usado en la TX, 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 TX |
Registra el punto de conexión
Después de configurar tu punto de conexión, registra la URL del punto de conexión de webhook en la sección de Integraciones (opens in a new tab) en el panel de Comercios, para que Bold sepa a donde enviar los eventos.
Formato de la URL de tu endpoint
El formato de la URL para registrar tu webhook es el siguiente:
https://<tu-website>/<tu-webhook-endpoint>
Para registrar tu punto de conexión debes:
-
Ve a la sección Integraciones (opens in a new tab) en el panel de Comercios. si ingresas por primera vez debes activar las llaves de autenticación con el botón + Activar llaves.
Estas llaves generadas (Llave de identidad) sirven para verificar la autenticidad de la información que es enviada a tu punto de conexión de webhook.
-
Luego de activar las llaves, ve a la sección Webhook, Haz clic en Configurar webhook
-
Agrega la URL HTTPS de tu punto de conexión de webhook en URL de punto de conexión y haz clic en Crear webhook.
-
Ahora verás el punto de conexión 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.
Asegura tu integración webhook:
Te recomendamos asegurar tu integración del punto de conexión de webhook con Bold. Para lograrlo, es importante verificar que todas las peticiones de webhook sean generadas exclusivamente por Bold.
Cómo verificar las firmas de webhook:
Para asegurar que la información provenga de Bold (autenticidad) 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 de identidad 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-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
//400 error response
Llave de identidad: puedes encontrar la llave de identidad en el módulo de integraciones del panel de comercios, llave de identidad. Para la renovación y generación de una nueva llave de identidad, puedes contactar a soporte (link soporte)