Tokenizing Credit Cards

Our Tokenization method via API supports generation of tokens which are returned in the response and can be stored for current and future use when creating new payments.

Tokenization of payment methods is on a per-terminal basis. Once you obtain a token, it can only be used to submit payments with the same terminal.

Tokenization is available on all terminals and does not require any special configuration.

Our tokenization involves sending a $0 authorization to the bank, so the card details and any supplied CVC/CVD values will be checked. To tokenize a card and receive a token, clients should submit a JSON request as follows:

POST /tokens
{
  "terminal": { "gateway_id": "YOUR_GW_ID" },
  "payment_method": {
    "credit_card": {
      "cardholder": "Bob Jones",
      "number": "4111111111111111",
      "expiry_month": "09",
      "expiry_year": "2024",
      "cvd": "123",
      "cvd_indicator": "1"
    }
  }
}

You can find the token details in the token_details field in the response. The token is a UUID.

{
  ...
  "token_details": {
    "cardholder": "Bob Jones",
    "last4": "1111",
    "expiry_month": "10",
    "expiry_year": "2024",
    "card_brand": "visa",
    "token": "9fd22452-a8ba-424c-bcce-9deb98f272a0",
    "token_type": "exactpay"
  }
}

To use that token with our Payment API, you must specify it as a payment method.

POST /payments
{
  "amount": 1012,
  "terminal": { "gateway_id": "YOUR_GW_ID" },
  "payment_method": {
    "token": {
      "token": "9fd22452-a8ba-424c-bcce-9deb98f272a0",
      "token_type": "exactpay"
  	}
  }
}

Our token is literally a reference to a previous transaction where we have saved the details of your original payment method. As such, you do not need to supply any details of the original payment method as we will use the values supplied at tokenization.

TransArmor Tokenization

TransArmor (TM) tokenization is supported for clients working with Fiserv/First Data or one of its Bank partners only. Contact Fiserv or your Bank partner for set-up.

TransArmor tokenization requires custom configuration, both at the terminal level and in your account with First Data and it is not enabled by default.

Once configured for a terminal, creating a payment on that terminal with our Payments API will generate a TransArmor token and return it in the response. You may then use that token in future payment requests in place of the original card number, however, you need to supply the other payment details such as expiry date, cardholder name etc.

To generate a token without processing a payment, we recommend you creating a zero-dollar authorization:

{
  "amount": 0,
  "capture": false,
  "terminal": { "gateway_id": "YOUR_GW_ID"},
  "payment_method": {
    "credit_card": {
      "cardholder": "Bob Jones",
      "number": "4111111111111111",
      "expiry_month": "10",
      "expiry_year": "2024"
    }
  }
}

You can find the token details in the payment_method_details field in the response. The token resembles a credit card number and the brand field indicates the card brand of the original card.

{
  ...
  "payment_method_details": {
    "cardholder": "Bob Jones",
    "last4": "1111",
    "expiry_month": "10",
    "expiry_year": "2024",
    "card_brand": "visa",
    "token": "7206364399711111",
    "token_type": "transarmor",
  }
}

When creating a payment with your TransArmor token, you are also required to include other details of the original payment method in your request. The token itself is only a substitute for the original card number. Here's an example of a $1.00 Purchase using a TransArmor token:

POST /payments
{
  "amount": 100,
  "terminal": { "gateway_id": "YOUR_GW_ID"},
  "payment_method": {
    "token": {
      "cardholder": "Bob Jones",
      "token": "7206364399711111",
      "token_type": "transarmor",
      "card_brand": "visa",
      "expiry_month": "10",
      "expiry_year": "2024"
    }
  }
}

Omitting either the card_brand or the expiry date will cause the transaction to fail, with the appropriate failure message.