Create token

This call generates a network token on behalf of a PAN. The flow is as follows.

Endpoint and method

Method: POST

Endpoint: https://api.cardtokens.io/api/token

Request parameters

Parameter name	Data type	Description
card.pan	String	Required. The cardholder PAN to convert into a network token. Please notice that this field must be encrypted using an RSA public key delivered by Cardtokens. Details about encryption are explained in the section Card encryption below.
card.expmonth	Integer	Required. The cardholder expiry month formatted as N2 (1 = 01).
card.expyear	Integer	Required. The cardholder expiry year formatted as N4 (e.g., 2099).
card.securitycode	String	Optionally. The CVV2 / CVC value of the card. For better conversion, the schemes advise adding the security code when available. Many issuers still validate on security code in the authorizations.
merchantid	String	Required. Unique identifier of the merchant received from Cardtokens when creating the merchant. The created network token will only work with this merchant id.
billingaddress.line1	String	Optional. Street 1 on billing address for the payment instrument. Format: Alphabetic, numeric, and the following alphanumeric characters: period (.), comma (,), single quote ('), hyphen (-), pound sign or hashtag (#), forward slash (/) and whitespace; maximum 140 characters.
billingaddress.line2	String	Optional. Street 2 on billing address for the payment instrument. Format: Alphabetic, numeric, and the following alphanumeric characters: period (.), comma (,), single quote ('), hyphen (-), pound sign or hashtag (#), forward slash (/) and whitespace; maximum 140 characters.
billingaddress.city	String	Optional. The city associated with the enrolled payment instrument. Format: Alphabetic, single quote ('), hyphen (-), and whitespace.; maximum 100 characters.
billingaddress.state	String	Optional. State or province code in ISO 3166-2 format, e.g., NY. Format: Alphabetic; maximum 3 characters.
billingaddress.country	String	Optional. Country in ISO 3166-1 alpha-2 format, e.g., US. Format: Alphabetic; maximum 2 characters.
billingaddress.postalcode	String	Optional. The postal code associated with the enrolled payment instrument. Note: This field does not support spaces (" ") in the middle of characters. Format: Alphabetic, numeric, e.g., spaces are not allowed; maximum 3–16 characters.

Response parameters

Parameter name	Data type	Description
scheme	String	The major scheme of the token. It can be one of “visa”, “mastercard” or “testscheme”.
token	String	The major scheme network token generated. Visa: The unencrypted field contains a token as a 13-16 character string. Mastercard: TokenNumber returned in field TokenDetailData from the Tokenize api call. This value is formatted as minLength: 9, maxLength: 19 and example: 5123456789012345 Test scheme: This is a 16 digit simulated mod10 compatible number starting with "1" (prefix).
tokenid	String	The unique reference of the token when communicating to the Cardtokens API. This reference must be stored locally as this value is the key reference to the token when communicating with the Cardtokens API.
expmonth	Integer	The expiry month of the token. E.g., 01. Formatted as N1/N2
expyear	Integer	The expiry year of the token. E.g., 2099. Formatted as N4
par	String	Payment account reference. Used for digital receipts and loyalty.

Encrypted example request

{
  "enccard": "NjAwNzIyMDAwMDAwMDAwNDYwMDcyMjAwMDAwMDAwMDQ2MDA3MjIwM………DAwNA==",
  "billingaddress": {
    "line1": "Gammel Havn 1",
    "line2": "",
    "city": "Aalborg",
    "state": "Northjutland",
    "country": "DK",
    "postalcode": "9000"
  },
  "merchantid": "33df271c57c6441785e03a116a35de98"
}

Unencrypted example request

{
  "card": {
    "pan": "6007220000000004",
    "expmonth": 2,
    "expyear": 2028,
    "securitycode": "000"
  },
  "billingaddress": {
    "line1": "Gammel Havn 1",
    "line2": "",
    "city": "Aalborg",
    "state": "Northjutland",
    "country": "DK",
    "postalcode": "9000"
  },
  "merchantid": "33df271c57c6441785e03a116a35de98"
}

Example response

{
  "scheme": "testscheme",
  "token": "1454545454878784",
  "tokenid": "529d7cb6a75e4bab8d71eb09dcd489e0",
  "expmonth": 2,
  "expyear": 2028
}

Card Encryption

To strengthen the security of sensitive credit card details, the structure “card” must be encrypted when creating tokens. That means this json object must be encrypted independently using a public key received by Cardtokens. Cardtokens will then decrypt the encrypted card object at runtime by an internal secure stored private key. This public key will be received when the account is setup at Cardtokens.

Encryption algorithm

The PAN is encrypted using RSA, the encoding is UTF-8 and the padding scheme from PKCS #1 v1.5.

The RSA public key used for the encryption is to be found within app.cardtokens.io from the menu Settings -> Certificates.

Steps for encrypting

• Transform the card JSON object to a JSON string
• Convert the JSON string into a byte array using UTF-8 encoding
• Encrypt the byte array using the public key
• Encode the binary encrypted byte array to a base64 string
• Set the value of enccard to the base64 encoded string, which contains the encrypted card details.