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 realizadas en linea.

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

Para transacciones realizadas en modo de pruebas, las notificaciones al webhook no se envían.

Sin embargo, para las integraciones en línea puedes utilizar la opción de "Probar el webhook" al finalizar la compra, solo aplica para las pruebas de integraciones en linea. Consulta mas detalles en la documentación del Ambiente de pruebas y conoce como utilizar esta opción.

¿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

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": "ORD-SHOP03-1719242727607215713"
    }
  },
  "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 NEQUI → pago por nequi BOTON_BANCOLOMBIA → pago por Botón Bancolombia
metadata.reference	string	Referencia de pago. Esta depende del tipo de integración: Applink (deeplink) valor definido en reference al crear el deeplink. Botón de pagos valor del atributo order-id, si no se define se toma el timestamp del momento de la transacción. API Link de pagos el valor del payment_link generado al crear el link de pago (inicia por LNK_). También recibirás notificación de las transacciones hechas por datáfono (*Solo para venta no presente).

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.

💡

Puedes registrar hasta 5 endpoints.

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

En modo pruebas la firma usa una clave vacia, es decir cuando se quiere veirificar una transacción que se realizo con las llaves de pruebas, el atributo donde va tu LLAVE_SECRETA no se ingresa, debe ir como un String vacio.

Ejemplo:

$secretKey = '';

Servicio de fallback del webhook

¿Para qué se utiliza?

El servicio de fallback te permite consultar activamente la notificación de una transacción asociada al último estado válido por el que ha pasado. Estos estados pueden ser:

SALE_APPROVED → “Venta aprobada”
SALE_REJECTED → “Venta rechazada”
VOID_APPROVED → “Anulación aprobada”
VOID_REJECTED → “Anulación rechazada”

¿Cómo se utiliza?

Obtén tus llaves de integración Como se explica en la sección de llaves de integración, es indispensable obtener tus llaves de integración para integrarte con las soluciones de Bold.

Una vez que tengas tus llaves, puedes proceder con el siguiente paso.

Realiza una solicitud a la URL:

 POST https://integrations.api.bold.co/payments/webhook/notifications/<payment_id>

Debes incluir el siguiente encabezado en la solicitud para que podamos identificar tu comercio:

Llave	Valor
Authorization	`x-api-key <llave_de_identidad>`

Asegúrate de reemplazar <llave de identidad> con la correspondiente a tu comercio.

Por ejemplo, si la llave de identidad es:

DZSkDqh2iWmpYQg204C2fLigQerhPGXAcm5WyujxwYH

Entonces el encabezado sería:

Llave	Valor
Authorization	x-api-key DZSkDqh2iWmpYQg204C2fLigQerhPGXAcm5WyujxwYH

Los parámetros disponibles son:

payment_id: Este es el identificador de la transacción que deseas consultar, puede ser el ID de la transacción o la referencia externa enviada al momento del pago.

Query params:

is_payment_id: Con este parámetro determinas si el parámetro payment_id corresponde al ID de la transacción o a la referencia externa enviada al momento del pago, por defecto su valor es True, Por lo tanto, si este campo no se envía, la búsqueda se realizará automáticamente por ID. Si en caso contrario deseas realizar la búsqueda por referencia externa, este parámetro debe ser enviado con valor false

Como respuesta, recibirás un cuerpo de la siguiente manera:

{
  "notifications": [ 
  //Lista de notificaciones que cumplen con la condición enviada. Se envía una respuesta por cada pago que cumple con la condición, con un máximo de 10 transacciones coincidentes
  ]
}

Por ejemplo, si queremos obtener la notificación de ejemplo ubicada en la sección “Crea el endpoint” tendríamos que hacer una petición a la siguiente URL:

 POST https://integrations.api.bold.co/payments/webhook/notifications/CP332C3C9WZU

o si quieres obtenerla por referencia externa, puedes usar la siguiente petición:

 POST https://integrations.api.bold.co/payments/webhook/notifications/ORD-SHOP03-1719242727607215713?is_payment_id=false

cualquiera de las dos peticiones te deberá retornar el siguiente resultado:

{
  "notifications":[
    {
      "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":"ORD-SHOP03-1719242727607215713"
          }
      },
      "datacontenttype":"application/json"
    }
  ]
}

Política de reintentos del webhook

Cuando tu sistema recibe una notificación de Bold, es crucial responder para confirmar la recepción correcta. Para esto debes enviar un código HTTP 200 (OK). En caso de no hacerlo, Bold intentará reenviar la notificación hasta obtener una confirmación de recepción HTTP 200 (OK) con un máximo de 5 reintentos.

Los reintentos de notificación seguirán el siguiente procedimiento:

# de reintento de notificacion	Tiempo desde el intento inicial
Primer reintento	15 min
Segundo reintento	1 Hora
Tercer reintento	4 Horas
Cuarto reintento	8 Horas
Quinto reintento	24 Horas

Consulta de transacciones API Integrations