menu

Payment API

What's on this page

Online Payments / Payment Features / PAN/IBAN Tokens

PAN/IBAN Token

A token is a unique and one-way generated hash of PAN or IBAN. It can be used to identify a card or bank account without the need to store the sensitive PAN or IBAN data in your system.

CCV Terminals are also able to calculate the PAN token which makes it possible to use a token generated upfront via the PSP API in a card-present environment. This is especially useful for parking entry and exit scenarios where the token can be used to identify the card during exit and link it to the entry transaction.

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 request using the Token API
  2. Redirect the customer to us using the payUrl
  3. We ask the customer for the PAN or IBAN in order to calculate the token
  4. When the calculation is done, we redirect the customer back to you using the returnUrl
  5. You read the token transaction using the Token API 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

Two types of token are supported, being card tokens 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

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 DE Web Token is calculated using the institute number and the account number and is always prefixed with 95.

Other Countries

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

Token API

Go to OpenAPI Token API

Embedded card data

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.

The API is the same in both cases, but the integrator should be aware of the PCI implications of the chosen flow.

  • Resource: cardDataUrl e.g. https://onlinepayments.ccv.eu/token/carddata/embedded?reference=YOUR_REFERENCE_HERE
  • Method: POST
  • Content-Type: application/json
  • Authentication: None
  • Parameters
Name Required Description
pan Yes The primary account number. All spaces and dashes are removed

Example

{
  "pan": "67032222222222227"
}

Token data response:

  • Status Code: 200
  • Body: none