Notifications

Token Requestor Services sends notifications when there is a change in the status of tokens or onboardings. When receiving a notification, it is recommended to call the corresponding API to obtain more details about the change, so that you always have accurate and up-to-date information.

Before consuming this API, a registered merchant must exist on the platform and, in the case of token notifications, a previously generated token. For onboardings, the process begins with the creation or update of the record linking the merchant to the payment franchise.

Each notification includes a signature, which must be validated by the recipient to confirm that it comes from Token Requestor Services, guaranteeing the authenticity of the message and preventing sensitive information from being altered by third parties. This strengthens the security of the entire process in a simple and reliable way.

The signature is a cryptographic value generated from the combination of specific message data and a secret key. Its purpose is to ensure that the notification has not been tampered with during transmission and that it comes from a legitimate source.

Signature generation typically follows this process:

• Key data such as the message content and generation date are combined.
• A hash function is applied along with a secret key shared between the sender and receiver.
• The result is a unique digital signature that the receiver can recalculate to verify the message's authenticity.
• To validate the signature, the receiver must recalculate it using the same data and the same secret key. If the result matches the signature received, it confirms that the notification is legitimate and has not been altered.

Notification Recipients

Notifications generated by Token Requestor Services can be received by both a consumer and a site.

Delivery depends solely on the prior configuration made by each:

• If the consumer has configured a notification URL along with its secret key, it will receive the notification.
• If the site also has its notification URL and secret key configured, it will also receive the notification.
• If both are configured, both will receive the notification independently.
• If no one has this configuration, the notification will not be delivered to anyone.

This way, the system guarantees flexibility in delivery, ensuring that each actor receives the notification only if they are ready to validate and process it.

Token Notifications

Token notifications are generated when a change occurs in the status of a token, whether it is created, updated, expiry, or deleted. This allows external systems to stay synchronized with the actual information of the payment methods associated with the merchant or site.

Flow

1. When a change is recorded in a token, the platform first internally updates the token information. This includes the current status, expiration date, and any additional relevant details.
2. Once the token is updated, an internal event is triggered indicating that the token has changed and that it is time to notify the configured recipients.
3. Depending on the configuration, a notification is sent to the associated site, the consumer, or both. Each notification contains the token information, the generation date, and the security signature.
4. The recipient validates the signature to ensure the notification originates from Token Requestor Services and has not been altered.
5. Once validated, the recipient can process the notification and take additional actions as appropriate, such as updating their own records or notifying other internal systems.

Onboarding Notifications

Onboarding notifications are generated when a merchant's onboarding process with a payment franchise is created, updated, or completed. They allow consumers to receive real-time information on the status of this link, whether approved, pending, or failed, facilitating coordination and immediate action for merchants.

Flow

1. An onboarding process is initiated or updated for a merchant.
2. The system generates an internal event indicating that there has been a change in the onboarding status.
3. If the consumer has a notification URL configured, the relevant information is sent, including the onboarding ID, franchise, merchant ID, and updated status.
4. The notification includes a signature to verify that it comes from a trusted source and that the data has not been modified.
5. Consumers can process the information automatically to enable the merchant, retry a failed onboarding, or perform any other actions associated with the status change.

Examples

Notifications generated when the status of a managed resource in Token Requestor Services changes. This can include both payment tokens and merchant onboarding processes. Each notification provides the current status of the resource, the date of the change, and includes a signature that allows verifying the authenticity of the message.

{
    "type": "TOKEN_UPDATED",
    "siteId": "2972c13d-6315-4da3-80d7-64c24eb232ad",
    "signature": "Base64(SHA-256(secretKey + data + date))",
    "date": "2023-01-19 15:57:23",
    "data": {
        "id": "d8677265-03d2-4ffd-bf1e-9831073c1b11",
        "status": "INACTIVE",
        "expiration": "01/26"
    }
}