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. Every network token is paired with a PCI token that holds the same card. When you provision from a session, pan, or wallet_token source, Guardian creates that PCI token for you; with the pci_token source, it uses the one you name. The network token’s pci_token_id field identifies it.

Deleting tokens

Because the lifecycles are separate, deleting one token leaves the other in place:
  • Deleting a network token keeps its PCI token, and with it the stored card number. If you no longer need the card, also delete the PCI token named in pci_token_id.
  • Deleting the PCI token keeps the network token. The network token’s card still shows the masked card number, but expiry_month and expiry_year are null, and you can no longer fall back to the PCI token.

Provisioning Sources

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

Agentic Commerce

For agent-initiated payments, Visa provisions a network token with its agentic presentation type (AI_AGENT in Visa’s terms) instead of ECOM. Agentic commerce support lets you choose it per token, as presentation_type: "agent".
Agentic commerce is a gated feature. It is off on every instance until it is activated for yours. Contact your account manager to activate it.
With agentic commerce support on your instance:
  • Choose the presentation type. Create token accepts presentation_type, ecom or agent, for every source. Without it, the token is provisioned with ecom. A token keeps its presentation type for its whole life.
  • Read Visa’s token ID. Visa’s agentic services identify a token by Visa’s provisioned token ID, not by Guardian’s ID. Every response for an agent token carries it as network_token.scheme_reference.
agent is supported with Visa Token Service only. A request for a card that is provisioned with another token service is refused: 400 with the classifier NETWORK_TOKEN_NOT_SUPPORTED, or 422 with SCHEME_UNSUPPORTED when you promote a wallet token. On a sandbox instance, the simulated token service accepts agent, so you can build against it. On an instance without agentic commerce support, a request that carries presentation_type returns 403 with the classifier FORBIDDEN, even for ecom. Every network token response carries network_token.presentation_type: ecom or agent for a Visa Token Service token, and null for other token services.

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 TPAN encrypted, like the card number of a PCI token, and never returns it. The API returns only the masked number, its BIN and last four digits, and the token’s expiry. The plaintext TPAN never leaves the card data environment; it is only available through a cryptogram request.
When the data becomes 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. Until the token’s expiry is known, expiry_month and expiry_year are null; they never fall back to the card’s expiry.
  • Visa reports the full TPAN and its expiry 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. Every cryptogram reports the TPAN and its expiry again. On every token lifecycle event, Guardian also looks the token up at Visa, which gives the token’s expiry, so a renewed expiry is picked up.
  • 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. Lifecycle notifications update the BIN, the last four and the PAR. The expiry follows with the first cryptogram.
  • Visa Acceptance TMS reports only the PAR at provisioning. Once the token is active, Guardian looks it up on every lifecycle event, which gives the BIN, the last four and the expiry. Every cryptogram does too.
  • Tokens provisioned before Guardian stored these fields receive them with their next cryptogram or lifecycle event. Mastercard tokens also get their PAR through a backfill run by Hellgate; Visa tokens provisioned earlier stay without one.
Every cryptogram and lifecycle event updates the stored data with the latest values the token service reports, so a renewed expiry or a replaced token number is picked up. Each change sends one network.token.updated webhook. The payload carries no token fields, so fetch the token to read them. The admin token lookup shows the masked number, the token’s expiry 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. An inline request sent with an X-Idempotency-Key header is held inside Guardian for its replay for the same time as a reference, 15 minutes by default. See Idempotency.

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. Use filters to change how a value is injected, for example {{ expiry_month | unwrap }} to emit it as its native type. Guardian doesn’t deduplicate forwards, and an X-Idempotency-Key header reaches the destination unchanged. See Idempotency.

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. Fallback needs the PCI token to exist. If it was deleted, pci_token_id still names it, but forwarding through it returns a 404.

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.