Tokenization

Why Tokenization?

Tokenization allows to convert your customer's payment details into a unique token that can be securely stored.

This allows you to offer:

• Recurring payments: a transaction in a series of transactions. The amount of recurring payments is fixed as well as the intervals of the payment. Its based on the customer's consent to allow the merchant to initate one or more future transactions. Example: TV streaming subscription with the same monthly bill.

• Unscheduled Card on File: contrary to recurring payments, the amount and the schedule of the transaction can be flexible. Examples: Automatic top ups of railcards or mobile phone subscriptions, where the bill changes according to amount of minutes used.

• Delayed charge: allows supplemental acccount charge after the initial payment has been processed. Example: A hotel needs to charge minibar expenses on top of the (already paid) original bill.

• No-show: allows a no-show-transaction. Usually used for fees that occur because the customer does not meet the terms of an agreement. Example: Customer has booked a hotel room but does not cancel the booking according to the hotel's cancellation policy.

How does it work?

After the customers enter their payment details, Unified Services will generate a token referring to the payment details used for this transaction.

Once the token is generated and you have received the tokenId as a result, you can initiate recurring payments (subscriptions) with the Tokenize recurring payment details call.

Initiate tokenization

There are two ways to initiate the tokenization of your customer's payment details - either in connection with a payment or independently of a payment.

Initiate tokenization with a payment

In order to initiate tokenization of the payment details entered by your customers during checkout, you use the Create payment's PaymentMethodDetails object.

The PaymentMethodDetails request body contains the type parameter. The possible values (among others) are:

• type: MerchantInitiatedPaymentWithToken

• type: PaymentWithToken

• type: InitialPaymentMethodTokenizationDetails

Since, in our case, we want to initiate the tokenization of the payment method details we choose:

"type":"InitialPaymentWithTokenizationDetails"

The required PaymentMethodDetails request body changes with the type parameter value. In our case, it looks like this:

{
  "expiryDate":"the expiry date of the card",
  "intervalDays":"the frequency of the payments",
  "type":"InitialPaymentMethodTokenizationDetails"

As a result, the first payment is initiated, and subsequent payments are set up according to the intervalDays parameter.

The response contains the TokenizationId which is required to receive the token with the Get token from tokenId request. The token is used for future calls you might send for these specific payment details.

Initiate tokenization without a payment

You might also want to tokenize payment details without an actual payment being made.

In that case, instead of the CreatePayment call, you send either:

• the Tokenize card details for future payments call or
• the Tokenize recurring payment details call (Subscriptions, CardOnFile)

Tokenize card details for future payments

The purpose of that call is to store your customer's payment details, so that they don't have to enter them again for future purchases (unscheduled Card on File).

{
  "tokenSecret": "string",
  "returnUrl": "string",
  "cardDetails": {

Here the pan parameter is the customer's card number.

The tokenSecret is a unique string defined by you and needed for future references to the tokenized payment details. To include this secret token allows you to add an extra layer of security to future payments.

The response contains the tokenizationId.

Tokenize recurring payment details

If you want to set up a subscription or store a card on file which you can use to initiate potential future payments from your customer, you send the Tokenize recurring payment details request.

Get token from tokenID

Now that you have successfully tokenized your customer's payment details, you can take further actions.

For all of these you need to get the corresponding token.

To get that token, you send the Tokenization Services Get token from tokenId__ request, with the tokenizationId added as a path parameter:

/unified-services/en-EU/api/tokens-v1/{tokenizationId}

If the successful, the response contains the token.

Verify a token

If you want to verify the token, you can send the Verify a token request.

The response will show the same tokenizationId you've sent as a path parameter.

Payment with token

Now that you have generated the token using your tokenizationId there are two ways to set up payments with token.

• Payment with token (Subscription OR CardOnFile)
• MerchantInitiatedPaymentWithToken

We will describe both of these options below.

Payment With Token

This is used for either CardOnFile payments or Subscriptions.

In both cases, the type parameter of the Create Payment call's paymentMethodDetails object must be set to PaymentWithToken. That results in a request body as shown below:

{
  "token":"the token you've got from Get token from tokenId call",
  "secret":"the value you've defined while tokenizing the payment details",
  "isRecurring":"true - if this is a subscription",

The example above works for recurring payments such as subscriptions or CardOnFile.

Alternately, if you want to allow your recurring customers to check out without entering their payment details again, the isRecurrung parameter must be false. In that case the recurringType parameter SHOULD be omitted.

Merchant Initiated Payment With Token

This call is used for the following scenarios:

• UnscheduledCardOnFile
• DelayedCharge
• NoShow

In all of these cases, the type parameter of the Create Payment call's paymentDetails object must be set to MerchantInitiatedPaymentWithToken.

{
  "token":"the token you've got from Get token from tokenId call",
  "secret":"the value you've defined while tokenizing the payment details",
  "merchantInitiatedTransactionType":"UnscheduledCardOnFile",

The request body now contains the merchantInitiatedTransactionType parameter. Here you can choose from three values:

UnscheduledCardOnFile: allows to initiate payments for flexible amounts and dates. The use of a hotel's minibar might be an example.

DelayedCharge: If you provide one time services repeatedly (lodging, travel), based on an agreement with your customer.

NoShow: Allows you to charge services to which your customer committed, but then failed to comply with the agreed terms as for example unattended reservations at hotels without cancellation.