Webhooks

Este serviço será responsável por notificá-lo sobre eventos relacionados ao ciclo de vida dos tokens e processos de autenticação OTP.

Processo de verificação da assinatura digital do request

A assinatura digital é um código HMAC-SHA256 que é construído usando o api-secret e uma série de bytes que contêm a concatenação do timestamp, endpoint e request body codificados em UTF-8.

Notificação de envio do OTP

Esta notificação webhook é enviada quando o sistema gera e envia um código OTP (One-Time Password) durante o processo de tokenização de um cartão.

O evento é disparado quando é necessária autenticação adicional do usuário para completar a tokenização do seu cartão em um dispositivo ou carteira digital.

Quando este webhook é enviado?

Este webhook é enviado nos seguintes cenários:

  • Quando o processo de tokenização é iniciado e a verificação por OTP é necessária

Informações contidas no evento

O webhook contém as seguintes informações:

  • Informações do token: origem da tokenização, ID do cartão e ID do usuário
  • Código OTP: o código de verificação gerado
  • Destinatário: para onde o código deve ser enviado (email ou telefone mascarado)
  • Método de contato: o canal utilizado para enviar o OTP (EMAIL ou SMS)

Manipulação do evento

Seu sistema deve:

  1. Verificar a assinatura digital do request usando os headers de autenticação
  2. Processar as informações do OTP para mostrar ao usuário onde procurar o código
  3. Responder com um código HTTP 2XX para confirmar o recebimento
  4. Em caso de erro (4XX ou 5XX), o sistema tentará reenviar
Parâmetros disponíveis
Header Parameters
X-Api-Keystringrequired
Este header permitirá identificar qual api-secret você deve usar no caso de múltiplos pares de api-key e api-secret terem sido configurados.
Exemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este cabeçalho contém a assinatura digital (timestamp + endpoint + body) que você deve verificar para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar o pedido.
Exemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contém o momento em que o pedido foi assinado em formato unix-epoch para que você possa verificar se a assinatura não expirou.
Exemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
O endpoint para o qual o pedido é feito e que você usou para gerar a assinatura. Use este cabeçalho para regenerar a assinatura a ser validada, compará-la com o endpoint do seu serviço e verificar se coincidem.
Exemplo: X-Endpoint: /{path_defined_by_you}
Body Parameters
event_idstringrequired
Identificador do evento
Exemplo: tokenization-send-otp
Enum: tokenization-send-otp
tokenobjectrequired
Informações do token do cartão
otpstringrequired
Código OTP gerado para a verificação
Exemplo: 123456
tostringrequired
Destino mascarado onde o OTP foi enviado (email ou telefone)
Exemplo: m***@example.com
contact_methodstringrequired
Método de contato utilizado para enviar o OTP
Exemplo: EMAIL
Enum: EMAILSMS
idempotency_keystringrequired
Chave de idempotência única para o evento
Exemplo: 123e4567-e89b-12d3-a456-426614174000

Esta seção foi útil para você?

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"
}
Respostas de amostra

Notificação de eventos de tokens

Adicione este endpoint ao seu serviço para que possamos comunicar as novidades dos seus tokens em tempo real.

Considerações

Esperamos uma resposta do tipo 2XX para garantir que você recebeu a notificação. Caso contrário, iremos reenviá-la.

Tipos de Eventos.

  • OTP_PENDING: nós o notificaremos quando um código OTP for necessário para completar a tokenização.
  • OTP_SENT: nós o notificaremos quando um código OTP for enviado ao usuário.
  • ACTIVATED: nós o notificaremos sempre que um token for ativado.
  • SUSPENDED: nós o notificaremos sempre que um token for suspenso.
  • DISABLED: nós o notificaremos sempre que um token for desativado.
Parâmetros disponíveis
Header Parameters
X-Api-Keystringrequired
Este header permitirá identificar qual api-secret você deve usar no caso de múltiplos pares de api-key e api-secret terem sido configurados.
Exemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este cabeçalho contém a assinatura digital (timestamp + endpoint + body) que você deve verificar para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar o pedido.
Exemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contém o momento em que o pedido foi assinado em formato unix-epoch para que você possa verificar se a assinatura não expirou.
Exemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
O endpoint para o qual o pedido é feito e que você usou para gerar a assinatura. Use este cabeçalho para regenerar a assinatura a ser validada, compará-la com o endpoint do seu serviço e verificar se coincidem.
Exemplo: X-Endpoint: /{lifecycle_path_defined_by_you}
Body Parameters
event_idstringrequired
Identificador do evento
Exemplo: tok-lifecycle-activated
Enum: tok-lifecycle-otp-pendingtok-lifecycle-otp-senttok-lifecycle-activatedtok-lifecycle-suspendedtok-lifecycle-disabled
card_idstringrequired
Identificador único do cartão
Exemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
user_idstringrequired
Identificador único do usuário
Exemplo: usr-23hJL4bm94q9BFEd2sGhBjY6xbH
token_external_idstringrequired
Identificador do token na bandeira
Exemplo: token_ext_123456789
statusstringrequired
Estado do token
Exemplo: OTP_SENT
Enum: OTP_PENDINGOTP_SENTACTIVATEDSUSPENDEDDISABLED
originstringrequired
Origem da tokenização
Exemplo: APPLE_PAY
Enum: APPLE_PAYGOOGLE_PAY
idempotency_keystringrequired
Chave de idempotência única para o evento
Exemplo: 123e4567-e89b-12d3-a456-426614174000

Esta seção foi útil para você?

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"
}
Respostas de amostra