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 three sources depending on your compliance level.
SourceMin. complianceDescription
sessionSAQ-A+Use Guardian SDKs to capture cardholder data and send it encrypted to the API.
panSAQ-D+Import full card data when you have the required compliance.
pci_tokenSAQ-A+Provision from an existing PCI token. Lifecycles remain independent.

​
Cryptogram Types

TypeDescription
ecomStandard e-commerce transactions.
dauthDelegated authentication; requires prior activation with the scheme.

​
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.
ModeDescription
inlineReturns the full cryptogram payload in the response. Allowed only when the instance compliance level is SAQ-D or RoC.
referenceKeeps the cryptogram inside Guardian and returns a short-lived, single-use cryptogram_reference. You then forward your outbound request through Guardian, which injects the cryptogram server-side.
Which modes you can use, and which one applies when you omit mode, depend on your instance’s compliance level:
Compliance levelAllowed modesDefault when omitted
SAQ-Areference onlyreference
SAQ-D, RoCinline or referenceinline
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:
PlaceholderDescription
{{ cryptogram }}TAVV cryptogram (null for dynamic CVV).
{{ dynamic_cvv }}Dynamic CVV (null for TAVV).
{{ eci }}Electronic Commerce Indicator.
{{ expiry_month }}Cryptogram expiry month.
{{ expiry_year }}Cryptogram expiry year.
{{ number }}The network token number (TPAN).
{{ type }}Cryptogram type: tavv or dynamic_cvv.
{{ metadata }} / {{ metadata.<key> }}Cryptogram metadata map, or a nested key.
{{ scheme_reference }}Scheme token reference.
{{ scheme_metadata }} / {{ scheme_metadata.<key> }}Scheme metadata map, or a nested key.
{{ status }}Network token status: active, inactive, deleted, or unprovisioned.
{{ supports_device_binding }}Boolean.
{{ network_token_id }}Network token UUID.
{{ network_token_type }}Network token type: vts, mdes, tms, or hgts.
{{ network_token_metadata }} / {{ network_token_metadata.<key> }}Network token metadata map, or a nested key.
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.