> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Network Tokens
> Manage network tokens and cryptograms
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](/platform/network-tokens).
## Provisioning
In Guardian, network tokens are provisioned **explicitly**. You create a network token with its own [API call](/products/guardian/api-reference/network/create-token), 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.
| Source | Min. compliance | Description |
| ----------- | --------------- | ------------------------------------------------------------------------------ |
| `session` | SAQ-A+ | Use Guardian SDKs to capture cardholder data and send it encrypted to the API. |
| `pan` | SAQ-D+ | Import full card data when you have the required compliance. |
| `pci_token` | SAQ-A+ | Provision from an existing PCI token. Lifecycles remain independent. |
## Cryptogram Types
| Type | Description |
| ------- | -------------------------------------------------------------------- |
| `ecom` | Standard e-commerce transactions. |
| `dauth` | Delegated 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](/products/guardian/api-reference/network/request-cryptogram) endpoint can return a reference to the cryptogram instead of the cryptogram itself. The `mode` field controls this.
| Mode | Description |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inline` | Returns the full cryptogram payload in the response. Allowed only when the instance compliance level is SAQ-D or RoC. |
| `reference` | Keeps the cryptogram inside Guardian and returns a short-lived, single-use `cryptogram_reference`. You then [forward](#forwarding-cryptograms) 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 level | Allowed modes | Default when omitted |
| ---------------- | ----------------------- | -------------------- |
| SAQ-A | `reference` only | `reference` |
| SAQ-D, RoC | `inline` or `reference` | `inline` |
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](/products/guardian/api-reference/network/forward-cryptogram)). This works like [PCI token forwarding](/products/guardian/tokens/pci-tokens#injection-of-sensitive-data): 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:
| Placeholder | Description |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `{{ 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. }}` | Cryptogram metadata map, or a nested key. |
| `{{ scheme_reference }}` | Scheme token reference. |
| `{{ scheme_metadata }}` / `{{ scheme_metadata. }}` | 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. }}` | 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](/products/guardian/api-reference/network/get-token-details) 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](/products/guardian/tokens/pci-tokens#injection-of-sensitive-data) instead — Guardian injects the FPAN in place of the TPAN and cryptogram.
```mermaid theme={null}
sequenceDiagram
autonumber
participant M as Merchant
participant H as Guardian
participant P as PSP / Acquirer
Note over M,P: Primary attempt — network token (TPAN)
M->>+H: Forward auth with cryptogram_reference
H->>+P: Authorize with TPAN + cryptogram
P->>-H: Authorization failed
H->>-M: Failure result
Note over M,P: Fallback — PCI token (FPAN)
M->>+H: Forward auth via PCI token
H->>+P: Authorize with FPAN
P->>-H: Authorization approved
H->>-M: Approved result
```
### 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.