Tokenization

Payment details tokenization allows for storing sensitive payment details inside the payments system. These can be later used via a reference for future payments. This can be useful for creating a (payment) wallet without storing all the payment method details locally and therefore reducing the complexity for creating a wallet. For example, storing credit card details locally means adhering to the PCI-DSS guidelines, whereas only storing a token avoids the PCI-DSS guidelines all together.

Tokenization is only supported for a select number payment methods. The following payment methods are supported:

• Bancontact (Wallet Initiated Payments, WIP).

For tokenized payments additional configuration on the account is required and in some cases an additional agreement may be required. Contact support or sales for more information.

Tokenization Flows

A token reference is always associated with a specific shopper and cannot be shared between shoppers. This means that a shopper must be created before calling the Tokenization API-endpoint, see also the Shoppers API-endpoint for more details on how to create a new shopper.

An order is not required during token registration. However, if no order (key) is given, then the system generates an order that is used for token registration. This (implicit) order has a value of 2 Euro cents, which will not be deducted from the shopper's account. This scenario is meant for adding a new payment method to a payment wallet.

Alternatively, an explicit order (key) can be provided during token registration. In this case, the amount of the order is deducted from the shopper's account. The use case here is to register a new payment method into a payments wallet and immediately pay for an order. Note that if the order is equal to or below 2 Euro cents, then the order is treated as an implicit order and no amount is deducted from the shopper's account.

Finally, it is important to note that the creation of a shopper only has to be done once per unique shopper. If a shopper wants to add or replace a payment method, then there is no need to register a new shopper in the system.

Register a Token without an Order

The data flow for token registration with an implicit order is shown below:

1. Create a shopper, the response contains the generated shopper key that needs to be used for the token generation.
2. Create a new token with the shopper key from step 1. This step generates a token key and an order key.
3. Get the available payment methods for the created order and show them to the shopper
4. Shopper completes the token registration by selecting a payment method and providing the required details.
5. Start the payment via a start payment request with the details provided by shopper.
   Redirected the shopper to the issuing bank for authentication.
6. Authentication is successful and token registration is completed. Two notifications are sent: one for the token and one for the order.

Register a Token with an Order

The flow for payment details tokenization with an order is shown below.

The data flow for token registration with an explicit order is as followed:

1. Create a shopper, the response contains the generated shopper key that needs to be used for the token generation and order creation.
2. Create a new order with the generated shopper key.
3. Create a new token with the shopper key from step 1 and order key of step 2.
4. Get the available payment methods for the created order and show them to the shopper.
5. Shopper completes the token registration by selecting a payment method and providing the required details.
6. Start the payment via a start payment request with the details provided by shopper.
   Redirected the shopper to the issuing bank for authentication.
7. Authentication is successful and token registration is completed.
   Two notifications are sent: one for the token and one for the order.

Start Tokenized Payment

An order can be paid using token. The flow is shown as below and is the same as starting a payment with actual (non-tokenized) payment details.

The data flow for paying an order with a token is as followed:

1. Shopper places an order and the order is created in the payment system.
2. A list of available tokens is retrieved for the order
3. A list of available payment methods is retrieved for the order (optional)
4. The shopper selects tokenized payment details.
5. The payment is started with the selected token.
   The system validates that the combination of Order Key, Shopper Key, and Token key are valid.
6. The result of the payment is returned. This can be that the payment is authorized, is canceled due to some conditions, or that the shopper needs to be redirected. See Starting a tokenized payment and Start Payment Request for more details.

Token Status Notification

A notification is sent when the status of a token changes, except when the token was just created, in an asynchronous manner. The used URL is configured on the account and is called 'Token Update URL'. The URL has a single replacement parameter ${token_key}, which identify which token changed. It is important to note, that the system performs an HTTP-GET request and that no information is sent, except for the token key. A token status call must be performed to determine the new status of the token.

Restrictions

• The Token Update Url works only with TCP ports 80 (http) and 443 (https), due to security constraints on the Payments platform. This restriction applies to both the production and sandbox environments.
• Any unknown or unmatched placeholder is replaced by a blank value, such that the resulting Url is still valid.