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

Obter tokens por ID do cartão

Este endpoint permite obter a lista de tokens associados a um cartão identificado pelo seu ID.

Suporta cursor pagination bidirecional mediante os parâmetros limit, start_from (paginaçã forward) e end_before (paginaçã 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 disponíveis
Query Parameters
filter[merchant_name]string
Filtro opcional para filtrar tokens por nome do comércio. Este filtro é guardado no cursor de paginação para manter a consistência entre páginas.
Exemplo: Amazon
filter[token_status]string
Filtro opcional para filtrar tokens por estado. Valores possíveis: OTP_PENDING, OTP_SENT, ACTIVATED, SUSPENDED, DISABLED. Este filtro é guardado no cursor de paginação para manter a consistência entre páginas.
Exemplo: ACTIVATED
Enum: OTP_PENDINGOTP_SENTACTIVATEDSUSPENDEDDISABLED
filter[token_requestor_id]string
Filtro opcional para filtrar tokens por identificador do solicitante do token. Este filtro é guardado no cursor de paginação para manter a consistência entre páginas.
Exemplo: 555555
limitinteger(minimum: 2, maximum: 100)
Tamanho máximo de página. Se não for especificado, o valor padrão é 50. O valor mínimo é 2 e o máximo é 100. Se um valor fora desses limites for fornecido, será normalizado automaticamente.
Exemplo: 50
start_fromstring
Cursor de paginação forward para obter a próxima página de resultados. Este cursor é exclusivo, ou seja, não será incluído na próxima página. Este valor é obtido do campo metadata.pagination.next_start_from da resposta anterior. O cursor inclui automaticamente os filtros aplicados (merchant_name, token_status, token_requestor_id) para manter a consistência entre páginas. Não pode ser usado simultaneamente com end_before.
Exemplo: eyJjYXJkX2lkIjoiY3JkLTIzaEpMNGJtOTRxOUJGZWQyc0doQmpZOXhiSCIsInNvcnRfa2V5IjoiVCN0b2tlbjEifQ==
end_beforestring
Cursor de paginação backward para obter a página anterior de resultados. Este cursor é inclusivo, ou seja, será incluído na próxima página sempre que cumprir com os filtros aplicados (se houver). Este valor é obtido do campo metadata.pagination.next_end_before da resposta anterior. O cursor inclui automaticamente os filtros aplicados (merchant_name, token_status, token_requestor_id) para manter a consistência entre páginas. Não pode ser usado simultaneamente com start_from.
Exemplo: eyJjYXJkX2lkIjoiY3JkLTIzaEpMNGJtOTRxOUJGZWQyc0doQmpZOXhiSCIsInNvcnRfa2V5IjoiVCN0b2tlbjUwIn0=
Path Parameters
external_card_idstringrequired
Identificador do cartão
Exemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
Detalhe de respostas
statusstring
Estado de la respuesta
Exemplo: ok
Enum: okerror
dataarray
Lista de tokens asociados a la tarjeta
metaobject
Metadata de paginação bidirecional para navegar entre páginas de resultados

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

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

Obter token por ID

Este endpoint permite obter a informação de um token identificado pelo seu ID.
Parâmetros disponíveis
Path Parameters
external_token_idstringrequired
Identificador do token
Exemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalhe de respostas
statusstring
Estado da resposta
Exemplo: ok
Enum: okerror
dataobject
Información de un token de tarjeta

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

GET/v1/tokens/{external_token_id}
Respostas de amostra
{
"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 um token específico. O token deve estar em estado ATIVADO para poder ser suspenso. Se o token já estiver suspenso, retorna o estado atual sem realizar alterações.
Parâmetros disponíveis
Path Parameters
external_token_idstringrequired
Identificador do token a suspender
Exemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalhe de respostas
statusstring
Estado da resposta
Exemplo: ok
Enum: okerror
dataobject
Informação do estado do token após uma operação de suspensão

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

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

Reativar token

Reativa um token específico. O token deve estar em estado SUSPENSO para poder ser reativado. Se o token já estiver ativado, retorna o estado atual sem realizar alterações.
Parâmetros disponíveis
Path Parameters
external_token_idstringrequired
Identificador do token a reativar
Exemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalhe de respostas
statusstring
Estado da resposta
Exemplo: ok
Enum: okerror
dataobject
Informação do estado do token após uma operação de suspensão

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

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

Remover token

Remove um token específico. O token deve estar em estado ATIVADO ou SUSPENSO para poder ser removido. Se o token já estiver removido (DESABILITADO), retorna o estado atual sem realizar alterações.
Parâmetros disponíveis
Path Parameters
external_token_idstringrequired
Identificador do token a ser removido
Exemplo: zkpcjjksxcpkrjoxrqzgmflfwwj654
Detalhe de respostas
statusstring
Estado da resposta
Exemplo: ok
Enum: okerror
dataobject
Informação do estado do token após uma operação de suspensão

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

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

Atualizar estado de tokens por ID de cartão

Atualiza o estado de todos os tokens associados a um cartão específico. Somente os tokens que estão em um estado válido para a transição solicitada são atualizados. Os estados válidos são: ACTIVE (reativa tokens suspensos), BLOCKED (suspende tokens ativados) e DISABLED (desabilita tokens ativados ou suspensos). Quando o estado é BLOCKED ou DISABLED, é necessário fornecer um statusReason. Quando o estado é ACTIVE, o campo statusReason é ignorado se vier na solicitação.
Parâmetros disponíveis
Body Parameters
statusstringrequired
Novo estado do cartão. Determina quais tokens serão atualizados e para qual estado. ACTIVE reativa tokens suspensos, BLOCKED suspende tokens ativados, DISABLED desabilita tokens ativados ou suspensos.
Exemplo: BLOCKED
Enum: ACTIVEBLOCKEDDISABLED
statusReasonstring
Razão da mudança de estado. Requerido quando o status é BLOCKED ou DISABLED. Quando o status é ACTIVE, este campo é ignorado se vier na solicitação.
Exemplo: Card blocked by user
Path Parameters
external_card_idstringrequired
Identificador do cartão
Exemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
Detalhe de respostas
statusstring
Estado da resposta
Exemplo: ok
Enum: okerror
dataobject
Dados de resposta com os IDs de tokens atualizados
errorobject
Informação do erro (nulo se a operação foi bem-sucedida)

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

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