Network Tokens

What are Network Tokens?

To align with the Card Scheme’s mandate, all merchants processing Merchant Initiated or Card Token Transactions will be automatically enrolled for Network Tokenisation by 1st October 2026. You do not need to make any changes to your integration, however we recommend upgrading to the latest version to begin leveraging the new request and response fieldsrequest and response fields.

A Network Token is a secure, digital replacement for a card’s Primary Account Number (PAN), issued by a card scheme (Visa, Mastercard). By replacing the consumer’s actual card details, means any intercepted data will be useless to bad actors.

Network Tokens are currently available for Visa and Mastercard transactions only.

Network Tokens can only be used with a designated:

Merchant

Card

For Visa Network Token transactions, the emailAddress field is required. If this field is not provided, Visa may be unable to provision a Network Token and the transaction will fall back to a non-tokenised flow.

Benefits of Network Tokens

PCI DSS compliant Reduces the scope of the sensitive data to be protected.

Enhances security Network Tokens replace the consumer’s actual card details, making intercepted data useless to cybercriminals.

Improves authorisation rate Network Tokens are automatically updated by the card network, allowing you to continue to process Merchant Initiated Transactions even after the physical card expires.

Reducing fraud Limiting the use of the card information to specific transactions, devices or merchants, Network Tokens helps to prevent unauthorised transactions, reducing fraud.

Judopay Card Tokens vs Network Tokens

What is the difference between a Judopay Card Token and a Network Token?

Judopay Card Token

Judopay Card Tokens are secure, system-generated tokens (strings) that replace the raw card details. The Card Token is linked to the saved card held securely in Judopay’s systems.

The card tokens represent a combination of a:

Card number

Expiry date

Locator Id

Consumer reference

Each Card Token is unique to a card, consumer and merchant. As Card Tokens do not expose sensitive card information, Card Tokens are considered a more secure form of payment than physical cards, reducing your PCI scope and helping to keep customer data secure.

When a Card Token is used, Judopay retrieves the underlying card details from our secure vault and sends them through the normal payment flow (Judopay -> Gateway -> Acquirer -> Issuer).

Network Token

Network Tokens are 16-digit tokens issued by the card schemes (Visa, Mastercard) as a secure alternative to the Primary Account Number (PAN). Each Network Token is unique to a specific card, merchant and transaction.

Network Tokens are automatically updated by the card schemes when a card is replaced or expires, which means you can continue to process Merchant-Initiated Transactions (MIT)s without disruption. This helps reduce declines caused by outdated card details and typically increases authorisation rates.

The Network Token replaces the PAN in the payment flow (Judopay -> Gateway -> Acquirer -> Issuer), improving security and lifecycle management.

To benefit from the enhanced reporting features related to Network Tokens, we recommend upgrading to the latest version of our API.

How Network Tokens Work

There will be an additional step in the payment processing journey in our backend.

START The consumer enters card details to make a payment.

REQUEST AND CREATION Judopay sends the card details to our tokenisation service, which in turn requests a Network Token from the card schemes.

AUTHORISATION For each transaction the token is sent along with a unique cryptogram, adding an extra layer of security.

DECRYPTION AND VERIFICATION The card scheme decrypts the Network Token to retrieve the card details and sends them to the issuer to verify the details are correct.

FINAL STEP Once approved, the transaction proceeds, with the original card details only being shared between the card scheme and issuing bank.

Utilising Network Tokens

Prerequisite

Network Tokens are suitable for use for all integration types. No integration work is required. To request Network Tokens to be enabled on your account, contact your Account Manager or Customer Support.

Network Tokens are currently available for Visa and Mastercard transactions only.

Managing your Transactions

Disabling Network Tokens

For any transactions where you do not want to use a Network Token, set the disableNetworkTokenisation flag. This is only required to be set when generating the payment session. For more details, see API Transaction Reference Documentation.

This flag is suitable for use on all integration types.

{
  "judoId": "100100100",
  "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
  "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134",
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99
  },
  "currency": "GBP",
  "amount": 10.99,
  "cardAddress": {
    "address1": "CardHolder House",
    "address2": "1 CardHolder Street",
    "town": "CardHolder Town",
    "postCode": "AB1 2CD",
    "countryCode": "826",
    "cardHolderName": "John Doe"
  },
  "expiryDate": "2028-02-05T16:28:32.8596+00:00",
  "isPayByLink": true,
  "emailAddress": "[email protected]",
  "mobileNumber": "7999999999",
  "phoneCountryCode": "44",
  "threeDSecure": {
    "challengeRequestIndicator": "challengeAsMandate"
  },
  "disableNetworkTokenisation": true,
}

Parameter	Description
disableNetworkTokenisation Optional	Default = false. Set to true to specify that network tokenisation should not be used for the specified transaction. Note: This is even if network tokenisation registration has been enabled on the account.

Tracking Network Tokens

The networkTokenisationDetails block provides details on whether a Network Token was created, or created and used for a transaction. To track if a Network Token was created, or created and used, check the status of these two response fields:

networkTokenProvisioned - Indicates if a Network Token was generated.

networkTokenUsed - Indicates if the transaction was processed using a Network Token. For the possible response field combinations, see Status CombinationsMa.

The virtualPan block provides the PAN-formatted representation of the Network Token.

lastFour - Last four of the virtual PAN.

expiryDate - Expiry of the virtual PAN.

These fields can be accessed in the following ways:

Judopay Portal - Transaction Details Page

CSV Download

API Transaction Response

"disableNetworkTokenisation" : false,
"networkTokenisationDetails": {
    "networkTokenProvisioned": true,
    "networkTokenUsed": true,
  "virtualPan": {
    "lastFour": "0196",
    "expiryDate": "0929"
  }
}

To test Network Token transactions, see Network Token Sandbox Testingt.

Account Updater

Account Updater applies when a transaction is processed using a Network Token. It does not update ordinary PAN-based or non-tokenised transactions. In the sandbox simulation, the physical test PAN is used only to provision the Network Token and prepare the test scenario. The Account Updater event is triggered by the subsequent request using the associated Judopay Card Token.

What is Account Updater?

Account Updater detects when a card has been updated by the issuer (for example, due to reissuance or replacement) and ensures transactions can continue without interruption.

This allows for:

Accurate detection of account update events.

Correct reporting and downstream billing.

Stored card details are aligned with the latest issuer-provided data.

How Account Updater Works

When a Network Token transaction is processed, Judopay evaluates whether the underlying card details have changed due to the card reissuance or replacement.

If an update is detected, the Network Token is refreshed with the latest card information provided by the network.

The transaction continues uninterrupted using the updated card details, without any action required from the merchant or consumer.

To test an account updater event, see Testing an Account Updater Event.r

Response Fields

The networkTokenisationDetails block provides details on whether an account update has occurred. The response will include the field, accountDetailsUpdated = true.

Example transaction response, where the account was updated:

"disableNetworkTokenisation": false, "amount": "1.01", "authCode": "1", "networkTokenisationDetails": { "networkTokenProvisioned": false, "networkTokenUsed": true, "accountDetailsUpdated": true, "virtualPan": { "lastFour": "7441", "expiryDate": "1126" } },

Field	Description
networkTokenProvisioned	Indicates whether a Network Token was created.
networkTokenUsed	Indicates whether a Network Token was used in the transaction.
accountDetailsUpdated	Indicates the card issuer has updated the underlying card details (for example, due to card reissuance or replacement), and the Network Token has been refreshed accordingly ensuring payments continue without interruption.
disableNetworkTokenisation	Indicates whether tokenisation was disabled on a transaction level.
virtualPan	Provides the PAN-formatted representation of the Network Token. lastFour Last four of the virtual PAN. expiryDate Expiry of the virtual PAN.

Status Combinations

When tracking if a Network Token was:

created or

created and used check the status of the networkTokenProvisioned and networkTokenUsed response fields.

The following matrix describes the possible field status combinations you may receive. All four combinations are valid and represent different stages in the Network Token lifecycle:

networkTokenProvisioned	networkTokenUsed	Definition
false	false	A Network Token was not created. The transaction used the PAN (card number) flow.
true	false	A Network Token was successfully created, but was not used for this transaction. This is common following a /savecard transaction, where the Network Token is provisioned for future use.
true	true	A Network Token was created and used to process the transaction.
false	true	A previously provisioned Network Token was reused. A new Network Token was not required for this transaction.