Tokenization

Check the Tokenization API reference here.

PPaaS provides a card tokenization idToken service to support PPaaS clients who want to offer their merchants a recurring consumer identification service. With the flexibility of our irreversible tokenization service, the merchant can offer the consumer access to this service omnichannel and enjoy the membership privilege ubiquitously. Data security is our top priority, and as such, our end-to-end tokenization process ensures the customer card information is secured at all times since the initial touchpoint.

Prerequisites

Ensure that you have completed the following prerequisites for card tokenization service:

• You have registered a developer account and completed the authorization part.

• Your payment device is enabled with a card tokenization service subscription.

Card tokenization (idToken) overall flow

1. A consumer arrives at a merchant store and makes a purchase transaction.

2. Merchant offers a membership service with automated functionalities from the next purchase onwards.

3. The consumer provides additional data requirements such as a phone number and gives consent, to store his information in a secured format for further card recognition.

4. Once the consumer visits any store of the merchant again, the consumer will get recognized from the tokenized membership card information.

5. After making a transaction, any related service subscribed by the merchant will receive the membership information along with the recent transaction for further operations.

Card tokenization (idToken) overview

The card token generated from the PPaaS tokenization service is constructed from the encrypted consumer’s card PAN and the related service information belonging to the group ID. Group ID definition is directly dependent on the service. For example, in the CLO service, group ID can be a “silver tier loyalty” or “gold tier loyalty” program.

Card tokenization (idToken) is flexible enough for any service requiring a consumer’s card recognition via a payment device and via a partner platform.

Card tokenization (idToken) service use cases

With the card tokenization (idToken) service, the merchant will be able to offer a service subscription to a consumer via a payment device and via a partner platform. The JSON Web Encryption (JWE) protocol is required for the membership service used through a partner platform. The JWE protocol is not mandatory for the service calling, directly from a payment device, as it’s automatically encrypted.

For each use case, use the relative API endpoints to support your user journey as each endpoint would require different technical information and parameters.

Service subscription via a payment device process flow

1. Activate the PPaaS tokenization service on your payment device

2. Complete a payment transaction through the payment device

3. Request for membership subscription via member enrolment endpoint, without additional encryption step

Service unsubscription via a payment device process flow

Service subscription via a partner platform process flow

1. Request a PPaaS public key from the API in the partner-crypto section

2. Encrypt the card PAN with the JWE protocol

3. Request PPaaS to register a card as part of member registration

Note that the PPaaS public key is not mandatory for each registration request.

A new PPaaS public key should be requested only in these scenarios:

1. When the current key expires

2. On regular basis according to security policy (monthly request is recommended)

3. If the current key has been compromised, you must revoke it by calling the PPaaS public key deletion endpoint and request for a new public key.

Service unsubscription via a partner platform process flow

1. Have a card subscribed to the membership service either from a payment device or from a partner platform

2. Request PPaaS to revoke a card from a membership with the card token value

Card tokens retrieval

To retrieve all the consumer card tokens under your membership program, you can easily fetch them through the group ID. For identifying your group ID, this value will be provided during the service provider onboarding. For the digital receipt service, the group ID will represent a digital receipt service provider, while a loyalty program will be identified as the group ID in case of CLO service.

Card tokenization (idToken) with bulk actions

PPaaS tokenization service offers subscription and unsubscription functions in bulk through the batching process. By calling the POST idToken batch, you can process several consumer cards for card enrollment. The POST idToken delete-batch endpoint will revoke the card tokens in bulk.

JWE protocol

PPaaS card tokenization (idToken) service usage, via a partner platform, requires the JWE protocol for card PAN encryption, refer to the Compact Serialization section in RFC 7516.

The JWE block is the concatenation of these blocks separated by '.'

JWE protected header

• Header containing keyId and algorithms to be used. For example: Header = {"kid":"PPaaS-RSA-1324V2","alg":"RSA-OAEP","enc":"AES256-GCM"}

• kid is the PPaaS keyId of the public key that is used to encrypt the private key

• alg is the algorithm that is used to encrypted the private key. For example: [RSA_OAEPWITHSHA_512 , RSA_OAEP_A256GCM ]

• enc is the algorithm that is used to encrypted the data. For example: [ AES_256_GCM ]

JWE encrypted key

'Encrypted Key' (encrypted CEK) that is used to encrypt the sensitive data ('Ciphertext').

Example: JWE_encrypted_key = Encrypt( RSA-OAEP, publicKey, privateKey_CEK )

JWE initialization vector

Initialization Vector value used by the encryption algorithm.

Example: JWE_initialization_vector = 0102030405060708090a0b0c (usually a random number)

JWE ciphertext

Encrypted sensitive data (PAN).

Example: JWE_ciphertext = Encrypt( AES-CTR-256, privateKey_CEK, initVector, PAN )

JWE authentication tag

Authentication value.

Example: JWE_Authentication_Tag = Encrypt(AES-GMAC-256, privateKey_CEK, (initVector, data) )

Example of PPaaS card tokenization (idToken) with all combined

BASE64URL( UTF8( JWE Protected Header ) ) . BASE64URL( JWE Encrypted Key ) . BASE64URL( JWE Initialization Vector ) . BASE64URL( JWE Ciphertext ) . BASE64URL( JWE Authentication Tag ) eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.AxY8DCtDaGlsbGljb3RoZQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw