Tokenization
Overview
Concepts
VF Reuse Token
Verifone's proprietary Reuse Token is a multi-use two-way token of a payment instrument that allows linking payment data to a token for payments-related future use.
VF Analytics Token
Verifone's proprietary Analytics Token is a multi-use one-way token that allows linking card data to a token to identify cardholders across sales channels. A VF Analytics Token cannot be used for payments. For security reasons, VF Analytics Tokens are one-way tokens. Verifone does not offer the possibility to de-tokenize a token into clear cardholder data once it was tokenized.
Possible use cases for VFI Proprietary Tokens
Token type | Use cases |
---|---|
VF Reuse Token | Capture a payment instrument for future use for transactions with stored credentials, or for omnichannel refunds, you can request a VF Reuse Token. Store this token in your systems for future payments-related use. |
VF Analytics Token | Group transactions done using same PAN without any interest in the PAN number itself, you can request a VF Analytics Token. Store this token in your own systems. |
Token Scope
The Token Scope was created to enhance Verifone's Global Proprietary Tokenization Service security. A Token Scope for individual tokens provides the possibility for a merchant to limit the validity and the type of generated tokens. By linking a Token Scope to an organisation, any individual token that is generated is only valid within the Token Scope requested for generation.
Using Verifone Tokenization
Creating a Token Scope in Verifone Central
To start using Verifone Tokens, create at least one Token Scope on Verifone Central. Applicable Token Scopes need to be linked with an Organisation. You can create any number of Token Scopes and link them to any number of Organisations, but while Requesting a Token (see details below), only one Token Scope can be used.
Once the organisation is created, it is required to set up token scopes via Verifone Central. The token scopes can be managed from the Organisation details page. Token scopes can only be created against Organisations with type Merchant Company. Token scopes can only be assigned to group with a different type. These scopes are inherited from the parent merchant company.
- Log into Verifone Central.
- Navigate to the organisation with type 'Merchant Company'.
- In the Token Scope section, click 'Add new token scope' and enter all mandatory information.
- Name - the name for the token scope. Use this field for an easy identification of the Token Scope.
- This Name is different from the Token Scope UUID that is being used within the Verifone system to recognize the token scope
- Token format - to define whether the Reuse Tokens that are being generated should be alphanumeric or numeric only
- This selection only affects Reuse Tokens, as the analytics token is fixed-form, 29-digits: 'VF' + 27 digit alphanumeric
- Token type - to define which type of tokens are allowed to be created under this Token Scope
- If 'Reuse + analytics' is selected, two Token values will be returned in one response (see below)
- In the Additional Settings section, you can optionally influence the following technical details for Reuse Tokens. For example, you want to create format-preserved Tokens. If you leave the fields blank, the Verifone default settings will apply.
- Token length - the token length can be a number between 1 and 255
- Card prefix length - determines how many digits from the original PAN are included as a prefix for tokens under this scope
- Card suffix length - determines how many digits from the original PAN are included as a suffix for tokens under this scope
- Fixed prefix - the provided value is left-padded with the tokens under this scope. The maximum length should not exceed 6 characters.
- Fixed suffix - the provided value is right-padded with the tokens under this scope. The maximum length should not exceed 4 characters.
- Token expiration time - the number of days before a token expires under this scope
- Name - the name for the token scope. Use this field for an easy identification of the Token Scope.
- Save the token scope.
Linking a Token Scope in Verifone Central
For organisations other than the Merchant Company, Token Scopes can be linked. Linking Token Scopes to certain organisations can be done via the same interface on the Organisation details page.
- Log into Verifone Central.
- Navigate to any organisation with a type other than 'Merchant Company'.
- In the Token Scope section, click 'Link new token scope' and select the Token Scopes which should be added to the organisation.
- Note: You can link any number of Token Scopes to any number of organisations, but when Requesting a Token, only one Token Scope can be used.
- Save the token scope.
Once linking Token Scope(s), where you will see the Name you have given to this Token Scope and the Token Scope UUID that is being used within the Verifone system to recognize the token scope. It is the Token Scope UUID that you will need later, when Requesting a Token.
Requesting a Token
Once at least one Token Scope is linked to at least one Organisation, that Organisation can request Token generation in either of the following ways:
- By filling out the token_preference object in a Create a checkout request (please find the API specifications here), or
- By filling out the token_preference object in an EncryptedCardPaymentRequest (please find the API specifications here), or
- By filling out the token_preference object in an Initiate a wallet payment request (please find the API specifications here), or
- By submitting a Create/Update Token Details request (please find the API specifications here)
Parameter | Description |
---|---|
token_scope | (required field) - refers to the Token Scope UUID under which the Token is created |
encrypted_card | (required field) - refers to the cardholder data encrypted using the Verifone provided public key (only in the Create/Update Token Details request) |
token_type | (optional field) - allows you to optionally limit which type of Token(s) you would like to receive as a response to this call |
token_expiry_date | (optional field) - allows you to optionally limit the expiry date of the Token you want to receive as a response to this call |
public_key_alias |
refers to the public key the cardholder data is encrypted with (only in the Create/Update Token Details request)
|
Scenarios for Create/Update Token details requests
- if the token_scope allows for the creation of both a Reuse and an Analytics Token, but the Merchant decides that as a response to this call, an analytics Token is sufficient
- if the default token_expiry_date is further in the future than what the Merchant needs for this Token
The Create/Update Token Details request either creates a Token, if one does not yet exist for the given encrypted_card details in the requested Token Scope, or it updates the token details with the expiry date.
Receiving a Token
If the API call is approved, Verifone will return a Token in the response.
After a first API call where a VF Reuse Token is requested and created, any following API calls with the same Token Scope and encrypted_card details will result in the same VF Reuse Token.
After a first API call where a VF Analytics Token is requested and created, any following API calls with the same encrypted_card details will result in the same VF Analytics Token.
An approved API will result in a '201' (or '200' for a Create/Update Token Details request) message, where in the token_details object, is a list of possible responses.
Parameter | Definition |
---|---|
reuse_token | (if requested) - the VF Reuse Token that must be saved and stored |
analytics_token | (if requested) - the VF Analytics Token that must be saved and stored |
token_expiry_date | the expiration date for the Token(s) |
token_scope | stating under which Token Scope this Token(s) was created |
token_status | the status of the Token(s) |
created_at | the date when the Token(s) was first created |
updated_at | the last date when the Token(s) was last updated and various card information-related fields |
A Merchant can receive a non 'Active' status back if a Token was already created for this Token Scope and encrypted_card details, and it is already 'Deleted' or 'Suspended'. See the Using the Token section below to learn how to change the Token status.
Storing the Token
Verifone currently does not offer features that allow the Merchant to view their available Tokens at once. That is why we recommend storing the Verifone Token ID yourself at the time you receive the response. There are two other ways how to obtain Token IDs after the approved response:
- If the Merchant knows the encrypted card details, they can submit a Create/Update Token Details request (please find the API specifications here), where the response will contain the Token Details associated with that Token Scope and with those encrypted card details.
- If the Merchant knows the Transaction UUID associated with the Transaction that originally resulted in a Token, they can search for the Transaction on Verifone Central. In the Transaction Details tab of the Transaction, the Reuse Token associated with that Transaction can be found.
Using the Token
Verifone currently offers the following ways how a Merchant can use the VF Tokens:
- The Merchant can initiate a Transaction with a VF Reuse Token by submitting the TokenPaymentRequest API call (please find the TokenPaymentRequest API specifications here)
- A VF Reuse Token is linked to a Token Scope, therefore a VF Reuse Token provided as part of a Token Scope can only be reused by the Merchant Entity that is part of the same Token Scope
- The Merchant can do transactions with stored credentials where the VF Reuse Token might also be needed (please see Transactions with Stored Credentials for further information)
- The Merchant can do various Token Management activities via Token Management API calls (please find the API specifications here)
- Token scopes can only be used by Organisations with type Merchant Site