Webhooks

Este servicio será el encargado de notificarte sobre eventos relacionados con el ciclo de vida de los tokens y procesos de autenticación OTP.

Proceso de verificación de la firma digital del request

La firma digital es un código HMAC-SHA256 que se construye usando el api-secret y una serie de bytes que contienen la concatenación del timestamp, endpoint y request body codificados en UTF-8.

Notificación de envío de OTP

Esta notificación webhook se envía cuando el sistema genera y envía un código OTP (One-Time Password) durante el proceso de tokenización de una tarjeta.

El evento se dispara cuando se requiere autenticación adicional del usuario para completar la tokenización de su tarjeta en un dispositivo o wallet digital.

¿Cuándo se envía este webhook?

Este webhook se envía en los siguientes escenarios:

  • Cuando se inicia el proceso de tokenización y se requiere verificación por OTP

Información contenida en el evento

El webhook contiene la siguiente información:

  • Información del token: origen de la tokenización, ID de la tarjeta e ID del usuario
  • Código OTP: el código de verificación generado
  • Destinatario: a dónde se debe enviar el código (email o teléfono enmascarado)
  • Método de contacto: el canal utilizado para enviar el OTP (EMAIL o SMS)

Manejo del evento

Tu sistema debe:

  1. Verificar la firma digital del request usando los headers de autenticación
  2. Procesar la información del OTP para mostrar al usuario dónde buscar el código
  3. Responder con un código HTTP 2XX para confirmar la recepción
  4. En caso de error (4XX o 5XX), el sistema reintentará el envío
Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: /{path_defined_by_you}
Body Parameters
event_idstringrequired
Identificador del evento
Ejemplo: tokenization-send-otp
Enum: tokenization-send-otp
tokenobjectrequired
Información del token de la tarjeta
otpstringrequired
Código OTP generado para la verificación
Ejemplo: 123456
tostringrequired
Destino enmascarado donde se envió el OTP (email o teléfono)
Ejemplo: m***@example.com
contact_methodstringrequired
Método de contacto utilizado para enviar el OTP
Ejemplo: EMAIL
Enum: EMAILSMS
idempotency_keystringrequired
Clave de idempotencia única para el evento
Ejemplo: 123e4567-e89b-12d3-a456-426614174000

¿Te resultó útil esta sección?

POST/token-send-otp
{
"event_id":
"tokenization-send-otp"
"token":{
"origin":
"APPLE_PAY"
"card_id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
"user_id":
"usr-23hJL4bm94q9BFEd2sGhBjY6xbH"
}
"otp":
"123456"
"to":
"m***@example.com"
"contact_method":
"EMAIL"
"idempotency_key":
"123e4567-e89b-12d3-a456-426614174000"
}
Ejemplo de respuestas

Notificación de eventos de tokens

Suma este endpoint en tu servicio para que podamos comunicarte las novedades de tus tokens en tiempo real.

Consideraciones

Esperamos una respuesta del tipo 2XX para asegurarnos de que recibiste la notificación. Caso contrario, volveremos a enviarla.

Tipos de Eventos

  • OTP_PENDING: te notificaremos cuando se requiera un código OTP para completar la tokenización.
  • OTP_SENT: te notificaremos cuando se envíe un código OTP al usuario.
  • ACTIVATED: te notificaremos cada vez que se active un token.
  • SUSPENDED: te notificaremos cada vez que se suspenda un token.
  • DISABLED: te notificaremos cada vez que se desactive un token.
Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: /{lifecycle_path_defined_by_you}
Body Parameters
event_idstringrequired
Identificador del evento
Ejemplo: tok-lifecycle-activated
Enum: tok-lifecycle-otp-pendingtok-lifecycle-otp-senttok-lifecycle-activatedtok-lifecycle-suspendedtok-lifecycle-disabled
card_idstringrequired
Identificador único de la tarjeta
Ejemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
user_idstringrequired
Identificador único del usuario
Ejemplo: usr-23hJL4bm94q9BFEd2sGhBjY6xbH
token_external_idstringrequired
Identificador del token en la bandera
Ejemplo: token_ext_123456789
statusstringrequired
Estado del token
Ejemplo: OTP_SENT
Enum: OTP_PENDINGOTP_SENTACTIVATEDSUSPENDEDDISABLED
originstringrequired
Origen de la tokenización
Ejemplo: APPLE_PAY
Enum: APPLE_PAYGOOGLE_PAY
idempotency_keystringrequired
Clave de idempotencia única para el evento
Ejemplo: 123e4567-e89b-12d3-a456-426614174000

¿Te resultó útil esta sección?

POST/token-lifecycle
{
"event_id":
"tok-lifecycle-activated"
"card_id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
"user_id":
"usr-23hJL4bm94q9BFEd2sGhBjY6xbH"
"token_external_id":
"token_ext_123456789"
"status":
"OTP_SENT"
"origin":
"APPLE_PAY"
"idempotency_key":
"123e4567-e89b-12d3-a456-426614174000"
}
Ejemplo de respuestas