Skip to main content

​
What are network tokens?

Network tokens serve as symbolic replacements for payment credentials. They replace PAN (Primary Account Numbers) and other sensitive card data with a unique string (non-sensitive data) in all parts of the payment flows. They are used to authenticating transactions and are unique to the card, the merchant and the transaction. Network Tokens are generated by card schemes like Visa or Mastercard in real-time as customers use their cards. In this way, security is enhanced by preventing the exposure of cardholder information to third parties. Commerce provides merchants with a cohesive strategy for network tokenization, simplifying the process of token creation, utilization, and management. With network tokenization, merchants have several advantages:
  • Reduced fraud rates
  • Increased authorization rates
  • Lower interchange fees
  • Tokens can be used for multiple PSPs

​
Commerce tokens and network tokens

Commerce tokens can be enriched with network tokens from the card schemes. Once a card payment method undergoes tokenization, and if the network tokens feature is enabled for your account, Commerce will request a network token from the card scheme and associate it with the token. If this operation is successful, the network token status is updated to active. To use the network tokens for payment authorization, a cryptogram must first be requested. This is created and used during the payment request as proof of token validation for card transactions requiring authorization. They help to authenticate the transaction and ensure its integrity. The sequence diagram below demonstrates how the process works to use network tokens and request a cryptogram.

​
Network token payments

​
Step 1: Request authentication data

Commerce allows you to create these cryptograms using a previously imported token. 
curl --request POST \
  --url https://api.hellgate.io/tokens/{id}/payment-data \
  --header 'content-type: application/json' \
  --data '{
    "amount": 10000,
    "currency_code": "EUR",
    "merchant_id": "afb55b3a-9997-4ddf-8026-a178fd8573cc",
    "reference": "1234567890"
  }'

​
Step 2: Decrypt authentication data

Commerce processes the request and returns the encrypted authentication data. This encrypted authentication data contains the network token and the cryptogram. For more information, please refer to our API documentation. The network token is used to authenticate the transaction, and the cryptogram is used to validate the network token. To decrypt the payload, follow these steps:
  • Use the encryption_key that was generated when the merchant was created
  • Use the encrypted_authentication_data string, which you receive as part of requesting a cryptogram response
Below is an example of how to perform decryption in Elixir. However, this can also be accomplished using your preferred programming language. 
merchant_key = "e4xeJFoL+8kQWrSwCyJLnC56WkGz8aGIE8uEoQJGYDs"
encrypted_authentication_data = "eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NNIiwiaXYiOiJpR2ZsaXRMajJxLXpaMkdHIiwidGFnIjoia1c2bWRTQkJJcHBLMWwzQW93ZFBFUSJ9..."

JOSE.JWE.block_decrypt(
  :sha256 |> :crypto.hash(merchant_key) |> JOSE.JWK.from_oct(),
  encrypted_authentication_data
) |> elem(0) |> Jason.decode!
The decrypted payload will be in JSON format and will appear as follows: 
{
  "cryptogram" => "AwAAAAkA+1rBeAMAnkbHgpAAAAA=",
  "eci" => "07",
  "network_token" => %{
    "expiry_month" => 3,
    "expiry_year" => 2030,
    "token" => "4895370017908176"
  }
}

​
Step 3: Authorize with your PSP

curl 'https://api.hellgate.io/forward' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: <HELLGATE-API-KEY>' \
  -H 'X-HELLGATE-TOKEN: d7d272f7-f0e8-44c6-9459-c60e1ef279d5' \
  -H 'X-DESTINATION-URL: https://checkout-test.adyen.com/v69/payments' \
  -H 'X-API-KEY-ADYEN-NAME: X-API-KEY' \
  -H 'X-API-KEY-ADYEN-VALUE: <ADYEN-API-KEY>' \
  --data '{
    "merchantAccount": "<adyen_merchant_account>",
    "reference": "Payment-0001",
    "amount": { "currency": "EUR", "value": 1234 },
    "paymentMethod": {
      "type": "networkToken",
      "brand": "visa",
      "expiryMonth": "3",
      "expiryYear": "2030",
      "number": "4895370017908176"
    },
    "mpiData": {
      "directoryResponse": "Y",
      "authenticationResponse": "Y",
      "tokenAuthenticationVerificationValue": "AwAAAAkA+1rBeAMAnkbHgpAAAAA=",
      "eci": "07"
    },
    "recurringProcessingModel": "CardOnFile",
    "shopperInteraction": "Ecommerce"
  }'

​
Supported card schemes

  • VISA
  • Mastercard
  • American Express (coming soon)
  • Discover (coming soon)
  • Diners Club (coming soon)