Webhooks de Tokenización

Este servicio será el encargado de notificarte cuando se envíe un código OTP durante el proceso de tokenización de tarjetas.

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
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_methodstring
Método de contacto utilizado para enviar el OTP
Ejemplo: EMAIL
Enum: EMAILSMS

¿Te resultó útil esta sección?

POST/cards/tokenization/v1/{your_host}/{path_defined_by_you}
{
"token":{
"origin":
"APPLE_PAY"
"card_id":
"card_123456789"
"user_id":
"user_123456789"
}
"otp":
"123456"
"to":
"m***@example.com"
"contact_method":
"EMAIL"
}
Ejemplo de respuestas