Tokenisation

Introduction

The tokens are surrogate values that replace Primary Account Number (PAN) stored electronically throughout the payments system. This single token allows you to reference previously used card details, giving you:

• Faster re-use of existing payment details
• No need to store the details in your systems, reducing PCI requirements

The only thing you need to store on your system is the token itself, a unique string, and map it to your customer's account details.

Payments API

1. Creating a token

To generate a Token for future use at the same time as submitting a payment, use the "createToken" object to set a Token up for multiple use (set reusable to "true"). In addition, you can create your own token, send it to us within the object, and set rules as to whether you want to decline payments with duplicate payment details.

To tokenise a payment card separately to a payment, POST the payload to /payment-tokens

If you supply a token value, we will store that, otherwise we'll generate a token value and pass it back to you in the response.

  "createToken": {
    "value": "optional - define your own token",
    "reusable": true | false,
    "declineDuplicates": true | false
   }

{
  "requestType": "PaymentCardPaymentTokenizationRequest",
  "paymentCard": {
    "number": "4012000033330026",
    "expiryDate": {
      "month": "12",
      "year": "24"
    }
  },
  "createToken": {
    "reusable": true,
    "declineDuplicates": false
  },
  "accountVerification": false,
  "additionalDetails": {
    "operatorId": "OPERATOR_ID_123XXX",
    "salesSystemId": "W-EU-H3866-FLS2"
  }
}

{
    "clientRequestId": "7ea3415f-62ba-4a1f-8c0f-3c933c1e0c87",
    "apiTraceId": "Y7gIvGrWgLTPAUE7rGOJaQAAAso",
    "requestStatus": "SUCCESS",
    "requestTime": 1673005244065,
    "country": "United Kingdom",
    "paymentToken": {
        "value": "838C36B4-133E-4068-BF50-99008A0DB003",
        "reusable": true,
        "declineDuplicates": false,
        "last4": "0026",
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "orderId": "R-e0b9cc9c-730b-4064-b81b-ff84327ce7ac",
    "ipgTransactionId": "84616111269"
}

In the above example, we are allowing our systems to generate a payment token for the given card details, and it sends it back with the value 838C36B4-133E-4068-BF50-99008A0DB003 for later use.

If you want to set your own value for the token, include the value attribute in the "createToken" object. If you do not include this, we will define the token value and return it in the response as value attribute in the "paymentToken" object. If set to true, the token can be reused. If false, it has only a single use.

2. Updating a token

You can update one or more Payment Tokens at a time, and change the settings associated with the Token or the payment card associated with the Token. To make these updates, make a PATCH to /payment-tokens using requestType PaymentCardPaymentTokenUpdateRequest.

The PaymentTokens object is a list, and can include multiple payment tokens. See the example below to see how to construct the payload. Each of the token objects below includes the updates required - these will automatically be written to the token record on our systems if the request is processed successfully.

{
  "requestType": "PaymentCardPaymentTokenUpdateRequest",
  "paymentTokens": [
    {
      "value": "1751905117310026",
      "reusable": true,
      "declineDuplicates": false,
      "paymentCard": {
        "number": "5424180279791732",
        "expiryDate": {
          "month": "03",
          "year": "21"
        },
        "securityCode": "977"
      }
    },
    {
      "value": "9877hkhk68688888ffgh",
      "reusable": true,
      "declineDuplicates": false,
      "paymentCard": {
        "number": "4773410012347324",
        "expiryDate": {
          "month": "12",
          "year": "26"
        },
        "securityCode": "123"
      }
    }
  ]
}

{
  "requestStatus": "PARTIAL_SUCCESS",
  "requestTime": "1554308829345",
  "errors": {
    "details": [
      {
        "message": "HOSTED_DATA_ID4773410012347324. Invalid credit card number: CreditCard [cardNumber=4773410...7324, expirationMonth=12, expirationYear=2026"
      },
    ]
  }
}

3. Using a token

Once the token is created and you have stored it against the customer’s account detail, you can use it to execute payments for the customer. To use a tokenised payment instrument, use the relevant PaymentToken* requestTypes.

{
  "requestType": "PaymentTokenSaleTransaction",
  "transactionAmount": {
    "total": 12.04,
    "currency": "EUR"
  },
  "paymentMethod": {
    "paymentToken": {
      "value": "1235325235236",
      "function": "DEBIT",
      "securityCode": "977"
    }
  }
}

When a customer is checking out, and you've previously tokenised their payment details mapped to their account, you can request token details to enable the customer to confirm they want to pay with the stored payment instrument.

To do this, use the GET endpoint, providing the tokenid to receive a PaymentTokenDetails response. Our suggestion is you use the last4 value and brand to enable the customer to correctly identify which payment instrument they wish to use, and then from there you can use the token value as in the example above.

👍

Example complete

You've now used the API to create and use a payment token. For detail on more operations, such as retrieval or deletion of tokens, see the API Reference

Hosted Payment Page

Creating a token

If you use a HTML form to initiate the payment, you can send the parameter hosteddataid together with the transaction data as a unique identification for the payment information in this transaction.

Depending on the payment type, credit card number and expiry date or IBAN and account holder name will be stored under this ID if the transaction has been successful. In cases where the submitted hosteddataid already exists for your store, the stored payment information will be updated.

If you want to assign multiple IDs to the same payment information record, you can submit the parameter hosteddataid several times with different values in the same transaction.

If you prefer not to assign a token yourself but want to let the Gateway do this for you, send the parameter assignToken and set it to ‘true’. The Gateway will then assign a token and include it in the transaction response as hosteddataid.

If you have use cases where you need some of the tokens for single transactions only (e.g. for consumers that check out as a “guest”, use the additional parameter tokenType with the values ‘ONETIME’ (card details will only be stored for a short period of time) or ‘MULTIPAY’ (card details will be stored for use in future transactions).

Using a token

If you stored cardholder information using the token, you can perform transactions using the hosteddataid without the need to pass the credit card or bank account data again.

Please note, that it is not allowed to store the card code (in most cases on the back of the card) so that for credit card transactions, the cardholder still needs to enter this value. If you use Fiserv's hosted payment forms, the cardholder will see the last four digits of the stored credit card number, the expiry date and a field to enter the card code.

When using multiple Store IDs, it is possible to access stored card data records of a different Store ID then the one that has been used when storing the record. In that way you can for example use a shared data pool for different distributive channels. To use this feature, submit the Store ID that has been used when storing the record as the additional parameter hosteddatastoreid.

Avoiding duplicate cardholder data for multiple records

To avoid customers using the same cardholder data for multiple user accounts, the additional parameter declineHostedDataDuplicates can be sent along with the request. The valid values for this parameter are ‘true’/’false’. If the value for this parameter is set to ‘true’ and the cardholder data in the request is already found to be associated with another hosteddataid, the transaction will be declined.

Javascript

Tokenization with JavaScript allows you to use the advantages of an API interaction (server-to-server) and at the same time benefit from a solution that keeps sensitive card details away from your own systems, alleviating compliance with the PCI Data Security Standard.

In a first step, you tokenize card details that you can then use for later payment transactions via API requests that include the token instead of card details.

This option gives you maximum flexibility for the look and feel of the entry form in your webshop while a JavaScript library encrypts the sensitive information before it hits your servers. This can be an alternative to a Direct Post integration if you are only looking for tokenization and plan to handle all subsequent steps with our APIs.

The JavaScript for tokenization works across multiple Fiserv solutions including our gateway.
Please see integration documentation here: Payment.js