API Reference / Token

Token

A token resource represents a tokenized PAN or IBAN.

Note: if you call the token resource in operating mode TEST, you will not get a real token. The simulated token contains the reversed pan with a prefix and should not be used to store in a production system.

Typical token creation flow

The general flow is:

1. You create a new token
2. Redirect the customer to us
3. We ask for the PAN or IBAN in order to calculate the token
4. When the calculation is done, we redirect the customer back to your shop
5. You read a token to get the token.

Status Verification

We do not expose the token to the customer. It is up to you to verify the status of the token request and act accordingly. Webhooks are provided to give you feedback, but this principle remains.

Token types

Three types of token are supported, being card, par and web tokens.

Card Token

A card token is a token calculated from the complete PAN of a credit or debit card. This token will always consist of the prefix 99 followed by 16 characters given a token of 18 characters long.

Example 991234567890123456

Par Token

The Payment Account Reference (PAR) is a value linked to the Primary Account Number (PAN) of a cardholder account. EMVCo introduced the industry-wide solution to address merchant and acquirer challenges resulting from tokenization. PAR links tokenized and PAN-based transactions without the need for a PAN as the linkage mechanism (1:1 PAR to PAN). PAR enables merchants & acquirers to maintain fraud, loyalty and reporting programs dependent on PAN today.

PAR is 29 characters long. The first four positions of the PAR contain the BIN Controller Identifier (specific for Mastercard or VISA). Mastercard’s Bin Controller Identifier is ‘5001’, that of VISA is ‘V001’. The remaining 25 positions reflect a unique, randomly assigned value.

Example 50012XXXXXXXXXXXXXXXXXXXXX678

Note: PAR tokens are only supported for Mastercard and VISA.

Web Token

A web token is calculated on (part of) the IBAN of a debit card. Reason for this addition to the Token Service Provider is that there are countries where the banks do no print the PAN on their debit cards. Examples are the Netherlands and Germany.

Netherlands

For the Netherlands the IBAN is as follows

Example NL91ABNA0417164300

• 2 char country code (NL)
• 2 char check digits (91)
• 4 char bank code (ABNA)
• 10 char account number (0417164300)

The NL Web Token is calculated using the 10 char account number and is prefixed with 96.

Note: The banks BUNQ and KNAB are not supported in the TSP. Example 961234567890123456

Germany

For Germany the IBAN is as follows

Example DE89370400440532013000

• 2 char country code (DE)
• 2 char check digits (89)
• 8 char bank code (37040044)
• 10 char account number (0532013000)

The bank code needs to be converted to the institute number using the table from the Bundesbank Germany. The NL Web Token is calculated using the institute number and the account number and is always prefixed with 95.

Others

For other countries there is no support for token calculation based on IBAN.

Token object

Example

{
  "type" : "token",
  "token" : "998171576462127534",
  "tokenMaskedInput" : "DE60xxxxxxxxxxxxxx6789",
  "status" : "success",
  "description" : "A token description",
  "language" : "eng",
  "metadata" : "CFED8B1C8B9F292500E2E837767900BF2448EE28",
  "reference" : "AC130090D6C19A09CD4B8B3EECCE199AD895B6E0",
  "created" : 1420106400000,
  "lastUpdate" : 1420106700000,
  "statusFinalDate" : 1420106700000,
  "returnUrl" : "http://shop?order=CFED8B1C8B9F292500E2E837767900BF2448EE28"
}

Token request

The token request is used to create a new token.

• Resource: /api/v1/token
• Method: POST
• Content-Type: application/json
• Authentication: basic auth
• Parameters

Token Request Details

The details object contains additional fields that are only used when requesting a par token.

Example card token request

{
  "returnUrl" : "http://shop?order=436D2D8278789F4B2D618E301C875708B58F7A82",
  "metadata" : "436D2D8278789F4B2D618E301C875708B58F7A82",
  "description" : "API token description",
  "language" : "eng",
  "tokenType" : "card"
}

Example par token request

{
  "returnUrl" : "http://shop?order=436D2D8278789F4B2D618E301C875708B58F7A82",
  "metadata" : "436D2D8278789F4B2D618E301C875708B58F7A82",
  "description" : "API token description",
  "language" : "eng",
  "tokenType" : "par",
  "details" : {
    "VASPlatformName" : "MyPlatform",
    "VASProgramName" : "MyProgram",
    "VASCustomerIdentifier" : "customer-12345"
  }
}

Token Response

• Status Code: 200
• Content Type: application/json
• Content: Token

Read token request

The token read request is used to read information of a given token.

• Resource: /api/v1/token?reference={reference}
• Method: GET
• Authentication: basic auth
• Parameters: reference: The unique reference of the token request

Read token response

• Status Code: 200
• Content Type: application/json
• Content: Token

PCI token request

If you have a PCI compliant environment you can also choose to transmit the sensitive PAN or IBAN information directly to obtain a token. Either the PAN or the IBAN should be filled in and a token will be calculated accordingly.

• Resource: /api/v1/token/pci
• Method: POST
• Content-Type: application/json
• Authentication: basic auth
• Parameters

Example

curl https://api.psp.ccv.eu/api/v1/token/pci -u apikey:

{
  "pan" : "6799998900000010062",
  "metadata" : "436D2D8278789F4B2D618E301C875708B58F7A82"
}

PCI token response

• Status Code: 200
• Content Type: application/json
• Content: Token

{
  "metadata": "436D2D8278789F4B2D618E301C875708B58F7A82",
  "reference": "T1506161514118975.1",
  "token": "995336783076747372",
  "tokenMaskedInput" : "6799xxxxxxxxxxx0062"
}

Token data request

Normally the payUrl is used to obtain the token data from the customer or token data is directly supplied via token data in the request. Alternatively, the customer can submit the card data from a mobile app or browser to the cardDataUrl without requiring authentication. However, PCI compliance may be required:

• If the card data is provided directly by the customer to the PSP, No PCI compliance is required. E.g.: Mobile app or browser uses the cardDataUrl to submit the card data directly to the PSP.

• If the card data passes through the integrator’s backend system, PCI compliance is always required. E.g.: Mobile app or browser submits card data to integrator’s backend system which in turn uses the cardDataUrl to submit the data to the PSP.

• Resource: cardDataUrl e.g. https://onlinepayments.ccv.eu/token/carddata/embedded?reference=YOUR_REFERENCE_HERE

• Method: POST

• Content-Type: application/json

• Authentication: None

• Parameters

Example

{
  "pan": "67032222222222227"
}

Token data response

• Status Code: 200