Tokenization

Card schemes prohibit merchants from storing card numbers unless they comply with the relevant parts of the PCI DSS guidelines so Tokenization is a process that converts your consumers' sensitive data into a security token, a process involving hashing, encryption and secret keys.

This mechanism increases consumers' security because sensitive data (e.g. card number) is sent only once over the internet and then a token is used for the future requests.

AceHub Tokenization is a server-to-server API that gives you the possibility to collect your consumers’ card information in a secure manner and replace it with a token (in the form of a GUID). This token can be used anywhere in the AceHub platform to either make payments or query information. It also removes the need for merchants’ servers to be PCI DSS compliant and does not require the consumer to send card data multiple times.

The main purpose of these tokens is to be reused in future transactions e.g. recurring payments, where the merchant might need to charge the same card periodically.

Since this token is just a reference number, it is useless outside of the AceHub environment so there is no risk for the consumer in case it is stolen.

Important: Token creation is only available for credit cards and debit cards.

The figure below shows the Tokenization concept implemented in AceHub:

AceHub - Tokenization Request FlowAceHub - Tokenization Request Flow

AceHub - Tokenization Request Flow

Create a Token

Key fields

Key fields used for token creation:

  • Business id
  • Customer id (optional)
  • Card number
  • Card expiry month
  • Card expiry year

If a token already exists in AceHub (and was previously created with the same key fields), the stored token will be returned instead of creating a new one.

For a payment or authorize transaction, AceHub can create a token if the field "tokenize" is set to true.

Note: AceHub will return the token information in the response only if the transaction is successful.

Token generation

The key information used to generate the token is as follows:

1. Header block

  • businessId

2. Customer block

  • customerId (optional)

3. Card block

  • number
  • expiryMonth
  • expiryYear

The token creation process is only available for credit cards.

Optional information

The following fields, if specified in the request, will also be stored in AceHub, but will not be directly involved in the token creation.

1. Customer block

  • email

2. Card block

  • holderName
  • issueNumber

Request - Response Example

Example - Tokenize

{
   "header":{  
      "businessId":"334455"
   },
   "body":{
     "brandId":1010,
     "card":{  
         "holderName":"John Doe",
         "number":"4916934502308682",
         "expiryMonth":12,
         "expiryYear":2020
     },
     "customer":{  
         "customerId":"98765",
         "email":"[email protected]"
     }
   }
}
{
    "result": 0,
    "header": {
        "requestTimestamp": "2017-07-10T15:37:50Z"
    },
    "body": {
        "token": "E942FA35-66E0-4264-8053-FFE73737D248",
        "displayHint": "************8682",
        "tokenStatus": "ACTIVE",
        "tokenType": "PAYVISION"
    }
}

Example - Payment with Tokenize

{
   "action":"authorize",
   "header":{
      "businessId": "334455"
   },
   "body":{
      "transaction":{
         "trackingCode":"7F4BFD5D-55E4-4775-81F7-0784188876C7",
         "brandId":1010,
         "amount":0.01,
         "currencyCode":"EUR",
         "countryCode":"NL",
         "tokenize":true
      },
      "card":{
         "holderName":"John Doe",
         "number": "4111111111111111",
         "expiryMonth":3,
         "expiryYear":2020,
         "cvv":"321"
      },
      "customer":{  
         "customerid":"123",
         "givenName":"John",
         "familyName":"Doe",
         "email":"[email protected]",
         "companyName":"Payvision",
         "IdentificationTypeId":1,
         "identificationNumber":"123456"
      },
      "billingaddress":{  
         "city":"Summerville",
         "street":"Main street",
         "houseNumberSuffix":"1",
         "streetInfo":"Longest street",
         "stateCode":"843",
         "zip":"29485",
         "countryCode":"US"
      }
   }
}
{
   "result": 0,
   "description": "Ok",
   "header": {
      "requestTimestamp": "2017-07-10T15:21:20Z"
   },
   "body": {
      "card": {
         "approvalCode": "799117",
         "expiryMonth": 3,
         "expiryYear": 2020,
         "firstSixDigits": "411111",
         "holderName": "John Doe",
         "lastFourDigits": "1111"
      },
      "transaction": {
         "amount": 0.01,
         "brandId": 1010,
         "currencyCode": "EUR",
         "action": "authorize",
         "id": "8d069ff8-1e4a-4139-8f50-2ce9b4caed7e",
         "trackingCode": "4f011aed-070a-4f04-ac06-bb833e3ded5f"
      },
      "token": {
         "token": "5C049E5B-3606-45C2-8CBF-6C0300D65E94",
         "displayHint": "************1111"
      }
   }
}