Network Tokens

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.

​

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)

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.