Network tokens are an add-on feature and may be subject to extra charges.
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 asession, 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
cardstill shows the masked card number, butexpiry_monthandexpiry_yeararenull, 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.
- Choose the presentation type. Create token accepts
presentation_type,ecomoragent, for every source. Without it, the token is provisioned withecom. 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
agenttoken carries it asnetwork_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:
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.
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.
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. Themode 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 acryptogram_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.
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
statusisinactive,deleted, orunprovisioned, 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.