Tokenization Guide

What is tokenization?

Creating frictionless payment journeys for repeat customers is widely considered a key enabler for consumer loyality. Traditionally, customers who returned to their preferred online shops and services for repeat business were obligated to enter their payment information each time. Often, the inconvenience of this exercise was enough for the customer to consider alternative suppliers.

Whilst most payment gateway have the ability to allow online businesses to capture and store the card information for themselves (in order to offer a 'One Click' service model), the constraints imposed by PCI DSS and good security practice - in addition to some well-known historic examples of card data breaches - left the majority of online merchants without a simple and secure mechanism for offering 'one-click' payment interactions.

Enter tokenization.

Tokenization is the practice of assigning a non-sensitive 'alias' (the 'token') to a consumer's payment card information and using this token for repeat payments. Since tokens can be stored without significant PCI or security implications, and can be consumed by a payment gateway as if it were the physical card information itself, tokenization is a practice that facilitates not only good security measures but also consumer payment journeys that augment loyalty.

Does N-Genius Online support tokenization?

Yes!

N-Genius Online utilizes a 'vault-less' tokenization model, whereby the same card information observed by the same merchant, will also generatet the same token 'value'.

As an example, if Shop X receives a payment from a consumer with card number ending 1234, the next time this card is used at Shop X, the resulting token value will be the same (1234). However, if the same card is used to purchase goods at Shop Y (a different merchant), the resulting token value will be different (i.e. 5678).

❗️

Token Group

In the Settings > Organizational Hierarchy section of your N-Genius Online merchant portal UI, there is a value called Token Group. This value is used as the secure key used to ensure that your tokens are always different to those of other merchants (and hence cannot be erroneously used elsewhere).

It is extremely important that you do not change this value unless under guidance from a Network International representative. Doing so will invalidate all tokens previously generated using the original key.

If, for any reason, there is a need to change this value (perhaps for the purposes of deliberately sharing your tokens with another N-Genius Online account), please ensure that you take note of the previous value, so that it can be restored if any problems are encountered.

Unlike 'vaulted' tokenization models, the 'vault-less' tokenization model allows greater flexibility in your business' use of tokens. If you have multiple shops/merchants, through the proper configuration of N-Genius Online, all of these entities can make use of the same tokens.

How do I use N-Genius Online's tokenization feature?

You may already be enabled to use tokenization if you are an N-Genius Online customer today.

However, if you are unsure, please check with your Network International Relationship Manager, or with our Customer Services team.

How do I use tokenization

There are two key steps to be undertaken in the production of a simple tokenization-enabled payments workflow with N-Genius Online.

1. Receiving token information

The first step to developing a tokenization-enabled payment workflow is to integrate with one of N-Genius Online's integration methods:

• Hosted Payment Page: see Hosted Payment Page
• Hosted Session / WebSDK: see Web SDK Integration Guide
• Direct API: see Direct API
• Mobile SDK: see Mobile SDKs

Once this is done, you will note that - irrespective of which N-Genius Online integration method you have chosen to use - there will always be script or page on a server controlled by you that interacts with the N-Genius Online APIs on your customer's behalf.

• With a Hosted Payment Page (HPP) integration, this script will likely be the one that controls order creation and/or retrieving the order outcome
• With a Hosted Session / WebSDK or a Mobile SDK integration, this script will be the one that controls the submission of the SessionId value for payment completion
• With a Direct API integration, this script will be the one (or more than one) interfacing with N-Genius Online in all payment interactions

If tokenization is enabled, you will notice the following JSON data in the _embedded.payment[X] block of payment outcome responses from the N-Genius Online APIs:

savedCard: {   
  “cardToken”: “[Base64 string]”,
  “cardholderName” : “Test Customer”, 
  “expiry”: “2025-04”,
  “maskedPan”: “401200******1112”,
  “scheme”: “VISA” }

Note: the X value in the _embedded.payment[X] location refers to the index of the payment against orders that have multiple payments associated with them. In most cases, X should be 0 (zero).

🚧

I'm not receiving the savedCard data

If you are not receiving the savedCard data in your payment outcome response, this will be because either tokenization is not enabled on your N-Genius Online account, or because the payment was not successful.

Tokens are not returned for unsuccessful payments.

If you are receiving tokens successfully, your next step should be to identify an appropriate way to store the data. Whilst not all elements of the savedCard data block will be used in all circumstances, we recommend that all elements in the block are saved on your systems.

We have observed some common ways of storing this data:

• A dedicated table in your database comprising all fields in the savedCard block, and a reference to the consumer/shopper to which it belongs (recommended)
• An additional field against your consumer/shopper database table, containing a Base64 encoded form of the full savedCard block

Now that you have received the savedCard data and storing it in your systems appropriately, we shall now describe how to use this data for triggering new payments, without requiring your shoppers to enter their full card information each time...

2. Using tokens for payment

There are two ways of presenting the savedCard token information to N-Genius Online for a new payment. However, in both cases you should always ensure that you are re-presenting the card information you have on file back to the shopper before proceeding for payment.

You can do this by making use of the maskedPan, expiry and scheme values from the savedCard data you have stored on your systems, i.e.

Pay with card '401200**1112' | VISA | Expiry: 2022-01

Your customer should now know which payment card they are going to be paying with, and have the opportunity to change it if they need to, before the payment is attempted.

Now that the customer is ready to pay, and knows which payment card they will be using for their next payment, we must now capture their CSC/CVV (Card Security Code).

To determine which method of presenting the savedCard information we will use for taking the new payment, we should decide how the CSC/CVV will be captured from the card-holder. As aforementioned, there are two ways of doing this:

a.) Capture the CSC/CVV on your page and consume the Direct API for submission of payment data
b.) Use the N-Genius Online Hosted Payment Page (HPP) to capture this information

Option a is typically a more frictionless experience and easier to implement, but is reliant (for security and PCI DSS reasons) on your site ensuring that the CSC/CVV data is not stored, and only used 'in transit' for constructing the API request.

Option b provides better innate security and PCI DSS compliance, but also requires an interruption of your shopper's payment experience to visit the N-Genius Online payment page. In this case, they will also have the option to change their choice of payment card, hence you may receive a different token returned at the end of the process.

2a. New payment via Direct API

In this model, we assume that the CSC/CVV value is being captured (temporarily) on your site immediately before payment is attempted.

The steps to implement this tokenization model are as follows:

1. Obtain an access token (see Request an access token )
2. Create an order for the new payment (see Two stage payments )
3. Locate the savedCard URI in the order creation response. You can find this in the _embedded.payment[X]._links block, defined as payment:saved-card.href
4. Construct a HTTP PUT request to this URI, using the relevant savedCard data as the payload:

HTTP Request Method: PUT
Resource (URI): value of _embedded.payment[X]._links.payment:saved-card.href

Headers:

Body:

Example request (body):

{
  "cardToken":"dG9rZW5pemVkUGFuLy92MS8vU0hPV19OT05FLy9nbDVxYXQ5bDFkaHh2MTg4",
  "expiry":"2021-12",
  "cvv":"123",
  "cardholderName":"Test Name"
}

📘

Relevant savedCard values

In this model of tokenized payment, only the cardToken, expiry, cvv and cardholderName are required inputs. Other fields, such as scheme and maskedPan are only relevant for direct consumer interactions, hence in this model they are not required inputs.

5. Submit the request
6. Process 3-D Secure challenge as required
7. Interpret result of payment

For steps 5-7, please return to Two stage payments, and follow the guidance as stated from the Submit payment card information step.