Skip to main content
Network tokens are an add-on feature and may be subject to extra charges.
For an overview of network tokens, how they work, and why to use them, see Network Tokens.

​
Provisioning

In Commerce, network tokens are provisioned automatically. 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 requests a network token from the card scheme and associates it with the token in the background. If this operation is successful, the network token status is updated to active. The network token’s lifecycle is aligned with the Commerce token — you do not provision or manage it separately.

​
Network token payments

To use a network token for payment authorization, a cryptogram must first be requested. It is created and used during the payment request as proof of token validation for card transactions requiring authorization, helping to authenticate the transaction and ensure its integrity. The sequence diagram below shows how to use a network token and request a cryptogram. Both the network token (TPAN) and its cryptogram are PCI-scoped data. You can consume a payment-data bundle in two ways:
  • Decrypt it yourself — read encrypted_authentication_data from the response, decrypt it with your merchant key, and send the network token and cryptogram to your PSP. This requires you to handle PCI-scoped data.
  • Forward without handling card data — let Commerce inject the network token, cryptogram, and related fields into your acquirer request server-side, so the raw values never reach your systems.
In the Managed Ecosystem operating model, encrypted_authentication_data is not returned. Use forwarding to authorize 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"
  }'

​
Forward without handling card data

If you would rather not decrypt and handle the network token and cryptogram yourself, forward your acquirer request through POST /payment-data/{id}/forward. Commerce forwards the request to the destination URL configured in your merchant settings and injects the PCI-scoped values via placeholders, so the raw network token and cryptogram never touch your systems. This is the only way to authorize payments in the Managed Ecosystem operating model. Reference each value with a placeholder in your request body:
PlaceholderDescription
{{ network_token }}Network token number (TPAN).
{{ cryptogram }}TAVV cryptogram.
{{ dynamic_cvv }}Dynamic CVV, when present instead of a TAVV.
{{ eci }}Electronic Commerce Indicator.
{{ cardholder_name }}Cardholder name.
{{ expiration_month }}Two-digit expiry month.
{{ expiration_year }}Four-digit expiry year.
{{ amount }}Authenticated amount in minor units.
{{ currency_code }}Currency code of the authenticated amount.
Number placeholders are strings by default; append | unwrap to emit the native type, for example {{ expiration_year | unwrap }}. See Forward payment-data for the full reference. Under the hood this builds on Guardian’s cryptogram forwarding.