PCI Tokenization API
The Forter Tokenization API allows merchants to create and manage tokens securely from their backend.
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/
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' }
});
Updated 5 months ago