Skip to main content
For an overview of network tokens, how they work, and why to use them, see Network Tokens.

​
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"
  }'

​
Advanced Token Management & Strategic Insights

Tokenization at scale introduces operational complexity that basic tooling can’t handle. The token management system is designed to give you full visibility into your token ecosystem, structured diagnostics when things go wrong, and the observability data you need to monitor and optimize performance over time.The token management interface is built to handle thousands of network tokens. You can navigate, filter, and inspect your full token inventory — active tokens and their associated network tokens — with a clear, real-time picture of what’s live and what needs attention. When tokenization failures occur, they surface structured error information including scheme-level failure reasons, giving you the context needed to identify whether a failure is recoverable, which scheme is the source, and where to focus optimization efforts.Failures from schemes
  • Tokenization Success Rate — track the share of successful tokenizations over time
  • Failures by scheme — isolate which networks are contributing to failures
  • Active Tokens / Network Tokens — monitor the size and health of your token base