Network Tokens

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.

Identifying a network token

Your processor shows a network token payment by the token’s own card-like number, the TPAN. To match it against a Commerce token, the token resource carries the TPAN in masked form next to the masked card number:

Field	Description
`masked_network_token_number`	The TPAN masked to its BIN and last four digits, for example `480012XXXXXX6777`.
`network_token_last_four`	Last four digits of the TPAN.
`payment_account_reference`	The PAR of the card, see below. Returned when scheme references are enabled for your account.

Filter the token list by the last four digits of the TPAN the same way you filter by the card number:

curl --request GET \
  --url 'https://api.hellgate.io/tokens?network_token_last_four=6777' \
  --header 'x-api-key: <HELLGATE-API-KEY>'

The value is four characters; anything else is rejected with a validation error. The filter only matches tokens whose digits are already stored. All three fields are also part of the token.created and token.updated webhook payloads, the PAR again only when scheme references are enabled. The network token is provisioned after the token is created, so token.created normally carries null digits; they arrive with a token.updated event.

Only the masked digits leave the card data environment. The full TPAN stays PCI-scoped and is only available through payment data.

The digits are filled in as the card scheme reports them: at provisioning for newly created tokens, and for tokens provisioned earlier on their next payment-data request or through a backfill run by Hellgate. Every change is announced by a token.updated webhook. Until then the fields are null while network_token_status is already active. Visa reports the PAR only at provisioning, so Visa tokens provisioned earlier stay without one. When the network token is deleted, the digits and the PAR are cleared.

Payment Account Reference

The Payment Account Reference (PAR) is a scheme-issued identifier for the underlying card account. The card number (FPAN) and every network token derived from it share the same PAR, so it lets you recognize one card across its tokens and across channels without handling card data. It cannot be used to make a payment.

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

Adyen v69

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:

Placeholder	Description
`{{ 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.

Getting Started

Payments

Tokens

Authentications

Wallets

Provisioning

Identifying a network token

Payment Account Reference

Network token payments

Step 1: Request authentication data

Step 2: Decrypt authentication data

Step 3: Authorize with your PSP

Forward without handling card data

​Provisioning

​Identifying a network token

​Payment Account Reference

​Network token payments

​Step 1: Request authentication data

​Step 2: Decrypt authentication data

​Step 3: Authorize with your PSP

​Forward without handling card data

Provisioning

Identifying a network token

Payment Account Reference

Network token payments

Step 1: Request authentication data

Step 2: Decrypt authentication data

Step 3: Authorize with your PSP

Forward without handling card data