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":
"DSHRMC1CO0303321afa9fb0a09b54051b21325c5 ..."
"status":
"activated"
"origin":
"GOOGLE_PAY"
"idempotency_key":
"3d5beafa-85af-3433-bee4-68d5a880634d"
}
Ejemplo de respuestas

Obtener tokens por ID de tarjeta

Este endpoint permite obtener la lista de tokens asociados a una tarjeta identificada por su ID

Soporta cursor pagination bidireccional mediante los parámetros limit, start_from (paginación forward) y end_before (paginación backward).

Tambien permite filtrar los resultados mediante los parámetros opcionales filter[merchant_name], filter[token_status] y filter[token_requestor_id]. Cada filtro soporta múltiples valores (por ejemplo: filter[merchant_name]=Amazon,Walmart). Los valores del mismo filtro se combinan con OR (ej: tokens de Amazon O Walmart), mientras que diferentes filtros se combinan con AND (ej: tokens de Amazon O Walmart Y con estado ACTIVATED)

{{Los filtros aplicados se guardan automáticamente en el cursor de paginación para mantener la consistencia entre las iteraciones de páginas, asegurando que los mismos filtros se apliquen en todas las páginas subsecuentes.

Parámetros disponibles
Query Parameters
filter[merchant_name]string
Filtro opcional para filtrar tokens por nombre del comercio. Este filtro se guarda en el cursor de paginación para mantener la consistencia entre páginas.
Ejemplo: Amazon
filter[token_status]string
Filtro opcional para filtrar tokens por estado. Valores posibles: OTP_PENDING, OTP_SENT, ACTIVATED, SUSPENDED, DISABLED. Este filtro se guarda en el cursor de paginación para mantener la consistencia entre páginas.
Ejemplo: ACTIVATED
Enum: OTP_PENDINGOTP_SENTACTIVATEDSUSPENDEDDISABLED
filter[token_requestor_id]string
Filtro opcional para filtrar tokens por identificador del solicitante del token. Este filtro se guarda en el cursor de paginación para mantener la consistencia entre páginas.
Ejemplo: 555555
limitinteger(minimum: 2, maximum: 100)
Tamaño máximo de página. Si no se especifica, el valor por defecto es 50. El valor mínimo es 2 y el máximo es 100. Si se proporciona un valor fuera de estos límites, se normalizará automáticamente.
Ejemplo: 50
start_fromstring
Cursor de paginación forward para obtener la siguiente página de resultados. Este cursor es excluyente, es decir que no se incluirá en la siguiente página. Este valor se obtiene del campo metadata.pagination.next_start_from de la respuesta anterior. El cursor incluye automáticamente los filtros aplicados (merchant_name, token_status, token_requestor_id) para mantener la consistencia entre páginas. No se puede usar simultáneamente con end_before.
Ejemplo: eyJjYXJkX2lkIjoiY3JkLTIzaEpMNGJtOTRxOUJGZWQyc0doQmpZOXhiSCIsInNvcnRfa2V5IjoiVCN0b2tlbjEifQ==
end_beforestring
Cursor de paginación backward para obtener la página anterior de resultados. Este cursor es incluyente, es decir que se incluirá en la siguiente página siempre y cuando cumpla con los filtros aplicados (si los hay). Este valor se obtiene del campo metadata.pagination.next_end_before de la respuesta anterior. El cursor incluye automáticamente los filtros aplicados (merchant_name, token_status, token_requestor_id) para mantener la consistencia entre páginas. No se puede usar simultáneamente con start_from.
Ejemplo: eyJjYXJkX2lkIjoiY3JkLTIzaEpMNGJtOTRxOUJGZWQyc0doQmpZOXhiSCIsInNvcnRfa2V5IjoiVCN0b2tlbjUwIn0=
Path Parameters
external_card_idstringrequired
Identificador de la tarjeta
Ejemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
Detalle de respuestas
statusstring
Estado de la respuesta
Ejemplo: ok
Enum: okerror
dataarray
Lista de tokens asociados a la tarjeta
metaobject
Metadata de paginación bidireccional para navegar entre páginas de resultados

¿Te resultó útil esta sección?

GET/v1/cards/{external_card_id}/tokens
Ejemplo de respuestas
{
"status":
"ok"
"data":[
0:{
...
}
]
"meta":{
"pagination":{
...
}
}
}

Obtener token por ID

Este endpoint permite obtener la información de un token identificado por su ID.
Parámetros disponibles
Path Parameters
external_token_idstringrequired
Identificador del token
Ejemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalle de respuestas
statusstring
Estado de la respuesta
Ejemplo: ok
Enum: okerror
dataobject
Información de un token de tarjeta

¿Te resultó útil esta sección?

GET/v1/tokens/{external_token_id}
Ejemplo de respuestas
{
"status":
"ok"
"data":{
"external_token_id":
"DSHRMC1CO0303321afa9fb0a09b54051b21325c5 ..."
"token_status":
"ACTIVATED"
"updated_at":
"2024-01-15T10:30:00.000"
"created_at":
"2024-01-15T09:00:00.000"
"origin":
"APPLE_PAY"
"user_id":
"usr-23hJL4bm94q9BFEd2sGhBjY6xbH"
"client_id":
"client-123"
"language":
"es"
"token_status_reason":
NULL
"card_id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
"from_push_provisioning":
true
"from_tap_to_add":
false
"token_requestor_id":
"555555"
"activated_at":
"2024-01-15T10:00:00.000"
}
}

Suspender token

Suspende un token específico. El token debe estar en estado ACTIVATED para poder ser suspendido. Si el token ya está suspendido, se retorna el estado actual sin realizar cambios.
Parámetros disponibles
Path Parameters
external_token_idstringrequired
Identificador del token a suspender
Ejemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalle de respuestas
statusstring
Estado de la respuesta
Ejemplo: ok
Enum: okerror
dataobject
Información del estado del token después de una operación de suspensión

¿Te resultó útil esta sección?

POST/v1/tokens/{external_token_id}/suspension
Ejemplo de respuestas
{
"status":
"ok"
"data":{
"external_token_id":
"zkpcjjksxcpkrjoxrqzgmflfwwj654"
"status":
"SUSPENDED"
}
}

Reactivar token

Reactiva un token específico. El token debe estar en estado SUSPENDED para poder ser reactivado. Si el token ya está activado, se retorna el estado actual sin realizar cambios.
Parámetros disponibles
Path Parameters
external_token_idstringrequired
Identificador del token a reactivar
Ejemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalle de respuestas
statusstring
Estado de la respuesta
Ejemplo: ok
Enum: okerror
dataobject
Información del estado del token después de una operación de suspensión

¿Te resultó útil esta sección?

POST/v1/tokens/{external_token_id}/unsuspension
Ejemplo de respuestas
{
"status":
"ok"
"data":{
"external_token_id":
"zkpcjjksxcpkrjoxrqzgmflfwwj654"
"status":
"SUSPENDED"
}
}

Eliminar token

Elimina un token específico. El token debe estar en estado ACTIVATED o SUSPENDED para poder ser eliminado. Si el token ya está eliminado (DISABLED), se retorna el estado actual sin realizar cambios.
Parámetros disponibles
Path Parameters
external_token_idstringrequired
Identificador del token a eliminar
Ejemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalle de respuestas
statusstring
Estado de la respuesta
Ejemplo: ok
Enum: okerror
dataobject
Información del estado del token después de una operación de suspensión

¿Te resultó útil esta sección?

POST/v1/tokens/{external_token_id}/deletion
Ejemplo de respuestas
{
"status":
"ok"
"data":{
"external_token_id":
"zkpcjjksxcpkrjoxrqzgmflfwwj654"
"status":
"SUSPENDED"
}
}

Actualizar estado de tokens por ID de tarjeta

Actualiza el estado de todos los tokens asociados a una tarjeta específica. Solo se actualizan los tokens que están en un estado válido para la transición solicitada. Los estados válidos son: ACTIVE (reactiva tokens suspendidos), BLOCKED (suspende tokens activados) y DISABLED (deshabilita tokens activados o suspendidos). Cuando el estado es BLOCKED o DISABLED, se requiere proporcionar un statusReason. Cuando el estado es ACTIVE, el campo statusReason se ignora si viene en el request.
Parámetros disponibles
Body Parameters
statusstringrequired
Nuevo estado de la tarjeta. Determina qué tokens serán actualizados y a qué estado. ACTIVE reactiva tokens suspendidos, BLOCKED suspende tokens activados, DISABLED deshabilita tokens activados o suspendidos.
Ejemplo: BLOCKED
Enum: ACTIVEBLOCKEDDISABLED
statusReasonstring
Razón del cambio de estado. Requerido cuando el status es BLOCKED o DISABLED. Cuando el status es ACTIVE, este campo se ignora si viene en el request.
Ejemplo: Card blocked by user
Path Parameters
external_card_idstringrequired
Identificador de la tarjeta
Ejemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
Detalle de respuestas
statusstring
Estado de la respuesta
Ejemplo: ok
Enum: okerror
dataobject
Datos de respuesta con los IDs de tokens actualizados
errorobject
Información del error (null si la operación fue exitosa)

¿Te resultó útil esta sección?

PATCH/v1/tokens/cards/{external_card_id}
{
"status":
"BLOCKED"
"statusReason":
"Card blocked by user"
}
Ejemplo de respuestas
{
"status":
"ok"
"data":{
"updateExternalTokenIds":[
...
]
}
"error":{}
}