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

​
Provisioning

In Guardian, network tokens are provisioned explicitly. You create a network token with its own API call, independently of any PCI token, and the two keep separate lifecycles — deleting or updating one does not affect the other. This gives you full control over when a network token is provisioned.

​
Provisioning Sources

Network tokens can be provisioned from four sources depending on your compliance level.

​
Token Digits and PAR

The network token object carries the masked token number (TPAN) so you can match a token against what an acquirer or processor shows, without ever handling the full TPAN: List tokens accepts a last_four filter:
The value must be exactly four characters. The filter is kept in the pagination links, so following next stays within the filtered result. It only matches tokens whose digits are already stored.
Guardian stores the BIN, the last four digits and the PAR, never the full TPAN. The plaintext TPAN never leaves the card data environment; it is only available through a cryptogram request.
When the digits become available depends on the scheme. Until the last four are known, masked_number is null; until the BIN is known, its prefix is all X.
  • Visa reports the full TPAN at provisioning, so the fields are normally set from the start. If the token data cannot be decrypted, Guardian keeps the last four Visa reports in plain form and completes the BIN with the first cryptogram. The PAR comes with provisioning only.
  • Mastercard reports the last four and the PAR at provisioning. The BIN is set at provisioning when the scheme returns a token BIN range; otherwise it follows with the first cryptogram.
  • Visa Acceptance TMS reports only the PAR at provisioning. The BIN and the last four follow with the first cryptogram.
  • Tokens provisioned before Guardian stored these fields receive the digits with their next cryptogram. Mastercard tokens also get their PAR through a backfill run by Hellgate; Visa tokens provisioned earlier stay without one.
Each time digits are stored, Guardian sends a network.token.updated webhook. The payload carries no token fields, so fetch the token to read them. Stored values are never overwritten. The admin token lookup shows the masked number and the PAR as well.

​
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.

​
Cryptogram Types

​
Cryptogram Modes

Both the network token (TPAN) and its cryptogram are PCI-scoped data. So that merchants with a lower compliance level can still use network tokens without ever handling a raw cryptogram, the Request cryptogram endpoint can return a reference to the cryptogram instead of the cryptogram itself. The mode field controls this. Which modes you can use, and which one applies when you omit mode, depend on your instance’s compliance level: Because every instance can use reference, building your integration around it lets the same code work on any instance. A cryptogram_reference is bound to the network token it was issued for and is rejected for any other token. It is single-use — invalidated after the first successful forward — and expires after a fixed TTL (15 minutes by default), whichever comes first.

​
Forwarding Cryptograms

When you hold a cryptogram_reference, send your outbound request to the acquirer through POST /api/network/tokens/{id}/forward (see Forward cryptogram). This works like PCI token forwarding: Guardian forwards your request to the third party and injects the sensitive, cryptogram-derived data on the fly. Pass the reference in the x-cryptogram-reference header and the target in the x-destination-url header. Define where to inject each value using placeholders: Injected values are strings by default. Append | unwrap to emit a value as its native type, for example {{ expiry_month | unwrap }}.

​
Fallback to PCI Token (FPAN)

Fallback is a retry pattern you orchestrate: detect the failed TPAN authorization, then forward the same payment through the PCI token. It applies on the Production tier, where authorizations route to real PSP and acquirer connections.
In production, an authorization attempted with a network token (TPAN) can fall back to the underlying card number (FPAN) held in a PCI token. Because the network token and the PCI token reference the same card, you can retry a failed TPAN authorization against the raw PAN without re-collecting card data. A network token on Hellgate carries a reference to its PCI token. The network token object includes a pci_token_id field — the ID of the PCI token that represents the same card. You don’t need to track the association yourself: read pci_token_id from the network token, then forward through that PCI token to fall back to the FPAN. When the network token path fails, retry by forwarding through the PCI token instead — Guardian injects the FPAN in place of the TPAN and cryptogram.

​
When Fallback Helps

  • Network token not yet usable — the token is still provisioning or its status is inactive, deleted, or unprovisioned, so the TPAN cannot be used.
  • TPAN authorization declined — some issuers or acquirer routes still approve the raw PAN where the token path is declined.
  • Scheme tokenization unavailable — cryptogram generation or the scheme token service is temporarily down.
  • Route without network token support — a given PSP or acquirer connection may not accept network tokens.
  • Preserve authorization rate — recover an otherwise lost sale rather than failing on a token-specific error.