Webhooks

This service will be responsible for notifying you about events related to the lifecycle of tokens and OTP authentication processes.

Digital signature verification process of the request

The digital signature is an HMAC-SHA256 code that is constructed using the api-secret and a series of bytes that contain the concatenation of the timestamp, endpoint, and request body encoded in UTF-8.

OTP shipping notification

This webhook notification is sent when the system generates and sends an OTP (One-Time Password) during the card tokenization process.

The event is triggered when additional user authentication is required to complete the tokenization of their card on a device or digital wallet.

When is this webhook sent?

This webhook is sent in the following scenarios:

  • When the tokenization process is initiated and OTP verification is required

Information contained in the event

The webhook contains the following information:

  • Token information: tokenization source, card ID, and user ID
  • OTP code: the generated verification code
  • Recipient: where the code should be sent (email or masked phone)
  • Contact method: the channel used to send the OTP (EMAIL or SMS)

Event handling

Your system must:

  1. Verify the digital signature of the request using the authentication headers
  2. Process the OTP information to show the user where to find the code
  3. Respond with an HTTP 2XX code to confirm receipt
  4. In case of an error (4XX or 5XX), the system will retry the sending
Available parameters
Header Parameters
X-Api-Keystringrequired
This header will allow you to identify which api-secret you need to use in case multiple pairs of api-key and api-secret have been configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that you must verify to ensure the integrity of the request. If the signature does not match, you must reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header contains the moment when the order was signed in unix-epoch format so you can verify that the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint to which the request is made and you used to generate the signature. Use this header to regenerate the signature to validate, compare it with your service endpoint, and verify that they match.
Example: X-Endpoint: /{path_defined_by_you}
Body Parameters
event_idstringrequired
Event identifier
Example: tokenization-send-otp
Enum: tokenization-send-otp
tokenobjectrequired
Card token information
otpstringrequired
OTP code generated for verification
Example: 123456
tostringrequired
Masked destination where the OTP was sent (email or phone)
Example: m***@example.com
contact_methodstringrequired
Contact method used to send the OTP
Example: EMAIL
Enum: EMAILSMS
idempotency_keystringrequired
Unique idempotency key for the event
Example: 123e4567-e89b-12d3-a456-426614174000

Was this section helpful to you?

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"
}
Response examples

Token event notification

Add this endpoint to your service so we can communicate updates about your tokens in real time.

Considerations

We expect a response of type 2XX to ensure that you received the notification. Otherwise, we will resend it.

Event types.

  • OTP_PENDING: We will notify you when an OTP code is required to complete the tokenization.
  • OTP_SENT: We will notify you when an OTP code is sent to the user.
  • ACTIVATED: We will notify you each time a token is activated.
  • SUSPENDED: We will notify you each time a token is suspended.
  • DISABLED: We will notify you each time a token is deactivated.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header will allow you to identify which api-secret you need to use in case multiple pairs of api-key and api-secret have been configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that you must verify to ensure the integrity of the request. If the signature does not match, you must reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header contains the moment when the order was signed in unix-epoch format so you can verify that the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint to which the request is made and you used to generate the signature. Use this header to regenerate the signature to validate, compare it with your service endpoint, and verify that they match.
Example: X-Endpoint: /{lifecycle_path_defined_by_you}
Body Parameters
event_idstringrequired
Event identifier
Example: tok-lifecycle-activated
Enum: tok-lifecycle-otp-pendingtok-lifecycle-otp-senttok-lifecycle-activatedtok-lifecycle-suspendedtok-lifecycle-disabled
card_idstringrequired
Unique identifier of the card
Example: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
user_idstringrequired
Unique identifier of the user
Example: usr-23hJL4bm94q9BFEd2sGhBjY6xbH
token_external_idstringrequired
Token identifier in the network
Example: token_ext_123456789
statusstringrequired
Token status
Example: OTP_SENT
Enum: OTP_PENDINGOTP_SENTACTIVATEDSUSPENDEDDISABLED
originstringrequired
Tokenization source
Example: APPLE_PAY
Enum: APPLE_PAYGOOGLE_PAY
idempotency_keystringrequired
Unique idempotency key for the event
Example: 123e4567-e89b-12d3-a456-426614174000

Was this section helpful to you?

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"
}
Response examples