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

Obtain tokens by card ID

This endpoint allows obtaining the list of tokens associated with a card identified by its ID.

Supports bidirectional cursor pagination through the parameters limit, start_from (forward pagination) and end_before (backward pagination).

{{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.}}

Available parameters
Query Parameters
filter[merchant_name]string
Optional filter to filter tokens by merchant name. This filter is stored in the pagination cursor to maintain consistency between pages.
Example: Amazon
filter[token_status]string
Optional filter to filter tokens by status. Possible values: OTP_PENDING, OTP_SENT, ACTIVATED, SUSPENDED, DISABLED. This filter is stored in the pagination cursor to maintain consistency between pages.
Example: ACTIVATED
Enum: OTP_PENDINGOTP_SENTACTIVATEDSUSPENDEDDISABLED
filter[token_requestor_id]string
Optional filter to filter tokens by the identifier of the token requestor. This filter is stored in the pagination cursor to maintain consistency between pages.
Example: 555555
limitinteger(minimum: 2, maximum: 100)
Maximum page size. If not specified, the default value is 50. The minimum value is 2 and the maximum is 100. If a value outside these limits is provided, it will be automatically normalized.
Example: 50
start_fromstring
Forward pagination cursor to obtain the next page of results. This cursor is exclusive, meaning it will not be included on the next page. This value is obtained from the metadata.pagination.next_start_from field of the previous response. The cursor automatically includes the applied filters (merchant_name, token_status, token_requestor_id) to maintain consistency between pages. It cannot be used simultaneously with end_before.
Example: eyJjYXJkX2lkIjoiY3JkLTIzaEpMNGJtOTRxOUJGZWQyc0doQmpZOXhiSCIsInNvcnRfa2V5IjoiVCN0b2tlbjEifQ==
end_beforestring
Backward pagination cursor to obtain the previous page of results. This cursor is inclusive, meaning it will be included on the next page as long as it meets the applied filters (if any). This value is obtained from the metadata.pagination.next_end_before field of the previous response. The cursor automatically includes the applied filters (merchant_name, token_status, token_requestor_id) to maintain consistency between pages. It cannot be used simultaneously with start_from.
Example: eyJjYXJkX2lkIjoiY3JkLTIzaEpMNGJtOTRxOUJGZWQyc0doQmpZOXhiSCIsInNvcnRfa2V5IjoiVCN0b2tlbjUwIn0=
Path Parameters
external_card_idstringrequired
Card identifier
Example: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
Response details
statusstring
Estado de la respuesta
Example: ok
Enum: okerror
dataarray
Lista de tokens asociados a la tarjeta
metaobject
Bidirectional pagination metadata to navigate between pages of results

Was this section helpful to you?

GET/v1/cards/{external_card_id}/tokens
Response examples
{
"status":
"ok"
"data":[
0:{
...
}
]
"meta":{
"pagination":{
...
}
}
}

Get token by ID

This endpoint allows obtaining the information of a token identified by its ID.
Available parameters
Path Parameters
external_token_idstringrequired
Token identifier
Example: zkpcjjksxcpkrjoxrqzgmflfwwj654
Response details
statusstring
Response status
Example: ok
Enum: okerror
dataobject
Información de un token de tarjeta

Was this section helpful to you?

GET/v1/tokens/{external_token_id}
Response examples
{
"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"
}
}

Suspend token

Suspends a specific token. The token must be in ACTIVATED status to be suspended. If the token is already suspended, the current status is returned without making changes.
Available parameters
Path Parameters
external_token_idstringrequired
Identifier of the token to suspend
Example: zkpcjjksxcpkrjoxrqzgmflfwwj654
Response details
statusstring
Response status
Example: ok
Enum: okerror
dataobject
Token status information after a suspension operation

Was this section helpful to you?

POST/v1/tokens/{external_token_id}/suspension
Response examples
{
"status":
"ok"
"data":{
"external_token_id":
"zkpcjjksxcpkrjoxrqzgmflfwwj654"
"status":
"SUSPENDED"
}
}

Reactivate token

Reactivates a specific token. The token must be in SUSPENDED status to be reactivated. If the token is already activated, the current status is returned without making changes.
Available parameters
Path Parameters
external_token_idstringrequired
Identifier of the token to reactivate
Example: zkpcjjksxcpkrjoxrqzgmflfwwj654
Response details
statusstring
Response status
Example: ok
Enum: okerror
dataobject
Token status information after a suspension operation

Was this section helpful to you?

POST/v1/tokens/{external_token_id}/unsuspension
Response examples
{
"status":
"ok"
"data":{
"external_token_id":
"zkpcjjksxcpkrjoxrqzgmflfwwj654"
"status":
"SUSPENDED"
}
}

Delete token

Deletes a specific token. The token must be in ACTIVATED or SUSPENDED status to be deleted. If the token is already deleted (DISABLED), the current status is returned without making changes.
Available parameters
Path Parameters
external_token_idstringrequired
Identifier of the token to delete
Example: zkpcjjksxcpkrjoxrqzgmflfwwj654
Response details
statusstring
Response status
Example: ok
Enum: okerror
dataobject
Token status information after a suspension operation

Was this section helpful to you?

POST/v1/tokens/{external_token_id}/deletion
Response examples
{
"status":
"ok"
"data":{
"external_token_id":
"zkpcjjksxcpkrjoxrqzgmflfwwj654"
"status":
"SUSPENDED"
}
}

Update token status by card ID

Update the status of all tokens associated with a specific card. Only tokens that are in a valid state for the requested transition are updated. The valid states are: ACTIVE (reactivates suspended tokens), BLOCKED (suspends activated tokens), and DISABLED (disables activated or suspended tokens). When the state is BLOCKED or DISABLED, a statusReason must be provided. When the state is ACTIVE, the statusReason field is ignored if it comes in the request.
Available parameters
Body Parameters
statusstringrequired
New card status. Determines which tokens will be updated and to what status. ACTIVE reactivates suspended tokens, BLOCKED suspends activated tokens, DISABLED disables activated or suspended tokens.
Example: BLOCKED
Enum: ACTIVEBLOCKEDDISABLED
statusReasonstring
Reason for the status change. Required when the status is BLOCKED or DISABLED. When the status is ACTIVE, this field is ignored if it comes in the request.
Example: Card blocked by user
Path Parameters
external_card_idstringrequired
Card identifier
Example: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
Response details
statusstring
Response status
Example: ok
Enum: okerror
dataobject
Response data with the IDs of updated tokens
errorobject
Error information (null if the operation was successful)

Was this section helpful to you?

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