Integration Guides

PCI Tokenization API

The Forter Tokenization API allows merchants to create and manage tokens securely from their backend.

Suggest Edits

Terms and definitions

  • Token - A series of randomly-generated characters, which replaces a Payment Method. A token is created after calling the Forter Tokenization API, which is then safe to store in your database.
    Our tokens look like the following: ftr19925f111ea16425fbd0d7bcd97c27005
  • Single use token - A token that is created from the client-side tokenization SDK (AKA Hosted Fields).
    • As the client-side tokenization SDK has limited authentication, this token is less trusted and will be deleted after 24 hours.
    • Single use tokens are the only type of token that can store CVVs. The reason is that legally, CVVs can only be stored until they're used, or up to 24hours.
  • Multi-use - The multi-use token is created by invoking the tokenization sever-side APIs.
    • Unlike a single-use token, multi-use token doesn’t have any usage limitation or expiration.
    • A single-use token can be upgraded to a Multi-use token with a special authenticated API call, but the CVV value will not be kept.

Authentication

The Forter Tokenization API uses HTTP Basic authentication in order to authenticate the merchant’s request. Provide the username and password via the “authorization” header in a basic auth format:

Header: “authorization: Basic TO_BASE64(site_id:site_secret)”

Sandbox environment

While integrating with Forter, you should use our sandbox environment which is free for use, and only requires your credentials.

URL (Sandbox Environment): https://pci-tokenization-sandbox.checkouttools.com/v1/

OpenAPI Schema: https://pci-tokenization-sandbox.checkouttools.com/documentation/json

NOTE: The sandbox environment can not store PCI information, and to that end only accepts hardcoded test PANS:
4111111111111111
4444333322221111
4646464646464644
349531373081938
5248480000201017
5555444433331111
If you require running a test using a specific test card (e.g. one that is issued by a third party), please let us know.

Production environment

One you are ready to transition to the production environment, you will need to contact us for production-specific credentials which are different from the sandbox environment. As a security measure, we will also ask you to provide the IP addresses of your backend instances that will make use of Forter's tokenization APIs.

URL (Production PCI Environment): https://pci.checkouttools.com/v1/

Client side authentication

In case you are using the Hosted Fields SDK, you will need to create a secondary, temporary, authentication token on each usage with the /client-key endpoint.

POST /v1/tokenization/tokenize

Receive PCI sensitive data and create a multi-use token for it

Note: If the tokenAliases parameter is used, the values used as aliases must be unique among all token aliases used in the past. The tokenization API call will fail if this is not the case.

const response = await axios.post('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/tokenize', {  
  cardNumber: "4111111111111111",  
  expirationMonth: 12,  
  expirationYear: 2028,  
  cardHolderName: "John Doe",  
  extra: {  
    additionalProp1: "string",  
    additionalProp2: "string",  
    additionalProp3: "string"  
  },  
  tokenAliases: {  
    externaltokenprovider1: 'EXTERNAL_TOKEN_123',  
    externaltokenprovider2: 'EXTERNAL_TOKEN_abc'  
  }  
}, {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` }  
});

POST /v1/tokenization/tokenize-single-use

Receive PCI sensitive data and create a single-use token for it - a token that can be used for up to 24 hours.
A single use token is are the only type of token that can store CVCs.
Note: In order to be fully PCI compliant, it is recommended that this token is deleted once it has been used for authorizing a transaction (by calling the delete endpoint).

Note: If the tokenAliases parameter is used, the values used as aliases must be unique among all token aliases used in the past. The tokenization API call will fail if this is not the case.

const response = await axios.post('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/tokenize-single-use', {  
  cardNumber: '4111111111111111',
  cvc: '123',
  expirationMonth: 12,
  expirationYear: 2028,
  cardHolderName: 'John Doe',
  siteId: siteId,
  extra: {  
    additionalProp1: "string",  
    additionalProp2: "string",  
    additionalProp3: "string"  
  },  
  tokenAliases: {  
    externaltokenprovider1: 'EXTERNAL_TOKEN_123',  
    externaltokenprovider2: 'EXTERNAL_TOKEN_abc'  
  }  
}, {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` }  
});

POST /v1/tokenization/detokenize

Receive a token and return the PCI sensitive data it holds

const response = await axios.post('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/detokenize', {  
    token: "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8"  
}, {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` }  
});

POST /v1/tokenization/upgrade

Receive a single-use token (created by Forter's Hosted Fields), and replace it with a new multi-use token.

Note: As mentioned above, this actions removes the stored CVV value.

const response = await axios.post('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/upgrade', {  
    token: "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8"  
}, {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` }  
});

POST /v1/tokenization/delete

Receive a token and delete it and its data

// Delete by token
const response = await axios.post('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/delete', {   
  token: "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8" 
}, {
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` }
});

// Delete by token alias
const response = await axios.post('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/delete', { 
  tokenAlias: { 
    key: "KEY", 
    value: "VALUE"
  } 
}, {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` }  
});

GET /v1/tokenization/token-info

Receive a token and return its non-PCI data.

const response = await axios.get('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/token-info', {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` },
  	params: { token: 'ftr1d8a56cfa6b3745a39e4a42d5ab1048c8' }
});

POST /v1/tokenization/client-key

Create an authentication token for the Hosted Fields SDK

Calling this endpoint is required before rendering a checkout form that uses Forter's Hosted Fields.

You are able to control the validity of the returned token using the ttlMinutes parameter, up to to 24 hours.

Note: It is recommended to use the smallest TTL value necessary for the end-user to successfully complete the transaction, in order to reduce the chance of abuse.

const response = await axios.get('https://pci-tokenization-sandbox.checkouttools.com/v1/tokenization/client-key', {  
    headers: { authorization: `Basic ${btoa(`${site_id}:${site_secret}`)}` },
  	params: { ttlMinutes: 60 }
});

Updated 19 days ago