Idempotency Keys for Network Token Provisioning
Retry a network token provisioning safely when its response is lost. Send anX-Idempotency-Key header with
Create token, for
any source, and repeat the request with the same key: Guardian provisions
and bills at most one network token per key. A repeat returns the original
status and response with the header Idempotent-Replayed: true, rendered
from the token’s current state. A key reused with a different request
returns 422 IDEMPOTENCY_KEY_MISMATCH, a repeat while the original runs
returns 409 IDEMPOTENCY_KEY_IN_USE, a malformed key returns 400
IDEMPOTENCY_KEY_INVALID, and a repeat whose token has been deleted since
returns 410 IDEMPOTENCY_KEY_TOKEN_DELETED. When the token service’s
answer was lost, a repeat provisions again. Outcomes are kept for 24 hours.
Requests without the header behave as before. See
Idempotency.Idempotency is switched on per instance. On an instance where it isn’t, the
header is ignored and every request is executed. The service configuration
on the admin dashboard shows whether it’s on as Idempotency Enabled; to
have it switched on, contact Hellgate support. Except for forwards, the
idempotency sections below apply only where it’s on.Idempotency Keys for PCI and Generic Token Creation
Create PCI token, from apan or a session source, and
Create generic token
now accept X-Idempotency-Key with the same contract: a retry with the same
key returns the original token, re-rendered as Get token shows it now, and
never a second one. A PCI token replay never returns the security code and
uses no second slot of your token limit; a generic token replay never
returns the payload. The card’s security code, source.security_code, is
left out of the same-request comparison for every covered write, including
network token provisioning from a pan source, so a repeat that differs
only in it replays the original. A refusal because the PCI token limit is
reached is stored and replays for 24 hours: send a new key after freeing
slots. A keyed PCI token create whose security code can’t be stored returns
503 CUSTODY_UNAVAILABLE, leaves no token, and can be retried with the
same key.Idempotency Keys for Cryptogram Requests
Request cryptogram now acceptsX-Idempotency-Key in both modes: a retry with the same key
returns the original cryptogram and never requests a second one. In
reference mode, a replay returns the original reference and its expiry,
also after the reference was forwarded or expired. In inline mode, Guardian
holds a keyed cryptogram for its replay for as long as a reference lives
(15 minutes by default); a later replay returns the original response with
number and cryptogram or dynamic_cvv set to null, so request a new
cryptogram with a new key. When the token service’s answer was lost, a
repeat requests a fresh cryptogram. See
Idempotency.Idempotency Keys for Wallet Tokenization
Tokenize Apple Pay and Tokenize Google Pay now acceptX-Idempotency-Key: a retry with the same key returns the
original wallet token, re-rendered as the tokenize response shows it now,
and never a cryptogram. A Google Pay payload sent again without a key also
returns 200 with the original wallet token instead of 409
GOOGLE_PAY_DUPLICATE_PAYLOAD, as Apple Pay already does; the 409 then
answers only a payload whose wallet token has been deleted. See
Idempotency.Idempotency Keys on Forwards
Forward card data, Forward cryptogram and Forward wallet token now document that anX-Idempotency-Key header reaches the destination
unchanged, whether or not idempotency is switched on for your instance.
Guardian doesn’t check the key and doesn’t deduplicate forwards, so whether
a repeat is safe is up to the destination. Forwards behave as before. See
Idempotency.Bugfixes
- A wallet token promotion refused because another request promoted the same wallet token at the same time is no longer billed, and leaves no network token behind.
- A cryptogram request whose token service answer Guardian can’t interpret
now returns
502instead of500. - When the configuration secret of a token service can’t be read, network
token provisioning, cryptogram requests and card art requests return
503SECRET_UNAVAILABLE, and you can retry. Provisioning used to return422for a secret store outage, or an unhandled500. A secret that doesn’t exist still returns422. - A network token provisioned from a
pansource whose security code can’t be held in custody returns503CUSTODY_UNAVAILABLEinstead of an unhandled500, with or without an idempotency key. No network token is stored; retry the request.
Network Token Creation Errors in the Specification
Create token now documents the errors Guardian already returns, each with an example:403
FORBIDDEN for each refusal by the instance, 404 NOT_FOUND for an
unknown pci_token or wallet_token source, 502 when a token service
answers with a server error, and 503
SECURITY_CODE_ENCRYPTION_UNAVAILABLE. A 502
carries the token service’s failure instead of Guardian’s error body: its
classifier, message, source, state and status_code, where state
tells whether repeating the request may succeed.Documentation only; Guardian’s behavior is unchanged.Agentic Commerce for Network Tokens
Provision Visa network tokens for agent-initiated payments. Agentic commerce is a gated feature: it has to be activated for your instance, so contact your account manager to activate it. Once it is active, Create token acceptspresentation_type: "agent", and responses for such tokens carry Visa’s
provisioned token ID as network_token.scheme_reference, without Delegated
Authentication. Without the field, a token is provisioned with ecom, as
before. agent works with Visa Token Service only; other token services
refuse it. Every network token response now also shows its
presentation_type. See
Agentic Commerce.In the Admin UI, the dashboard shows whether agentic commerce is enabled, a
network token’s details list its presentation type, and a provisioning in the
Activity tab shows the presentation type it was requested with.Bugfixes
- Promoting a wallet token whose card scheme doesn’t support network tokens was shown in the Activity tab with an unexplained failure. It now reads as an unsupported card scheme.
Classify Generic Token Payloads
Declare which values in a generic token’s payload are personal data. In a type’s JSON Schema, annotate a leaf withx-data-classification: pii; every
other leaf, and every key the schema doesn’t declare, is any. Guardian
checks the annotations when you create the type and refuses misplaced or
unknown ones with a 422 that names the location in the schema. See
Data classification.A generic token can also carry its schema inline: send schema instead of
type_id when you create it. The inline schema is checked like a type’s, the
payload is validated against it, and it stays on the token unchanged. It
doesn’t register a type, and it may be at most 32 KB as compact JSON and nest
at most 32 levels. Type and inline schemas are JSON Schema draft 2020-12, or
draft-07 when $schema names it. Token reads and the token list now return
both type_id and schema, with null for the one not used. A type read
returns its schema exactly as you wrote it. See
Payload schema.Network Token Expiry
The network token object now carries the token’s own expiry:network_token.expiry_month and expiry_year. They are null until a token
service reports them, and never fall back to the card’s expiry. Guardian now
stores the token number encrypted, like the card number of a PCI token, and
never returns it.Token data follows the token services: every cryptogram and every lifecycle
event updates it 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. Existing tokens send one with their next
cryptogram, when their token number and expiry are first stored. See
Token digits and PAR.Token Graveyard in the Admin UI
Deleted PCI, network and wallet tokens no longer appear in the Payment Cards search. The new Graveyard page lists them instead, newest deletion first, with their ID, type, scheme, last four, creation time and deletion time. Look one up by ID, or filter by type and deletion window. Each entry shows the token’s own activity trail. Opening a deleted token’s ID leads to its graveyard entry, and a live network token whose card was deleted shows that card as deleted, linked to its entry.Improvements and bugfixes
- Guardian now holds cryptograms and other sensitive authentication data only
in encrypted memory, never in its database. A wallet token’s cryptogram can
be forwarded for 24 hours by default; after that, or if it is lost, a
forward returns
400with the classifierCRYPTOGRAM_UNAVAILABLE, so tokenize a new payment. A cryptogram reference that can no longer be forwarded returns400withREFERENCE_UNAVAILABLE, so request a new cryptogram. When sensitive data can’t be held securely, the request returns503withCUSTODY_UNAVAILABLEand can be retried. A refused forward consumes nothing. - Cryptograms for Visa Acceptance TMS network tokens carried the card’s
expiry instead of the network token’s. They now carry the token’s, in the
cryptogram response and in forwarding templates (
{{ expiry_month }},{{ expiry_year }}). If TMS doesn’t report the token’s expiry, the card’s is used, as before. - A network token request that fails because the card scheme answered with a
server error now returns
502instead of400. - A
422with several validation errors lists them in a stable order, sorted by path. - A malformed type or inline schema, for example one that gives
enuma string, is now refused with a422andmust be a valid JSON schemainstead of failing with a server error.
Token Activity in the Admin UI
When a cardholder or your support team asks what happened to a card, the Activity tab of a PCI, network or wallet token now shows the answer. It lists every attempt to operate on or with the token, newest first, including failed ones. Each entry names who acted (a masked API key, an OAuth client, an operator, the card scheme or a background job), gives a plain-language failure reason, and carries a correlation ID you can copy.Filter the trail by time window, operation, outcome and channel. Activity on related tokens, such as the network token provisioned from a PCI token, is shown alongside by default.Payment Card Search in the Admin UI
Find a card without knowing its token ID. The Payment Cards page searches PCI, network and wallet tokens together, filtered by BIN, expiry range, metadata and related tokens. The filter refuses full card numbers, so none end up in your browser history or logs.Each token opens on a detail page that shows its type, full ID and state, the issuer’s card art where there is one, and tabs for related tokens and metadata.Improvements and bugfixes
- Guardian stores card numbers as digits only, whichever endpoint creates the
PCI token. Spaces and hyphens are removed, and a card number that isn’t 13
to 19 digits after that is rejected with a
422on every tier. Cards stored earlier keep the form they were stored in.
Improvements and bugfixes
- Deleting a PCI token now also clears its cardholder name. A network token
whose PCI token was deleted returns
card.cardholder_nameasnull, like the expiry fields. - Refreshing a card’s security code through a session now checks the code. A
code that isn’t 3 or 4 digits completes the session with status
failureand the reason codeINVALID_SECURITY_CODE, and a payload that can’t be decrypted fails withDECRYPTION_FAILED. Nothing is stored, so start a new refresh to try again.
Trusted Root Certificates Updated
For outbound connections, Guardian no longer trusts the emSign G3 root certificates from eMudhra or theAAA Certificate Services root. If a
destination you forward to presents a certificate chain that ends only at one
of these roots, the forward fails with a 502 and the classifier
PROXY_ERROR. The destination needs to present a chain to another publicly
trusted root.All Webhook Event Types in the Specification
The webhook event types in the API reference now include five that Guardian already sends:import.finished and import.failed when an import completes
or fails, and wallet.apple_pay.certificate.expiring_soon,
wallet.apple_pay.certificate.compromised and wallet.google_pay.key.disabled
for Apple Pay certificates and Google Pay keys. For these events,
related_object.url is null.The Webhooks page now also explains
how to acknowledge a notification, when Guardian retries, and how to handle
duplicates.Documentation only; Guardian’s behavior is unchanged.Zero-Padded Values in Forward Templates
Forward templates accept apad(n) filter that left-pads a value with zeros
to n characters. Use it where a destination expects fixed-width fields, such
as the YYMM card expiry date of an EMV 3DS request:3003 instead of 303. A value
already n characters or longer is left unchanged. A width outside 0 to 256 is
rejected with a 422 and the classifier PROXY_TEMPLATE_ERROR, before
anything is forwarded. See Filters.Bugfixes
- Network tokens provisioned through Visa Acceptance TMS now show the token’s
own digits.
last_fourandmasked_numberhad carried the last four digits of the card instead; Guardian cleared them, and the next cryptogram fills in the correct digits. - Visa Acceptance TMS tokens now carry their
payment_account_reference. Tokens provisioned earlier receive it with their next cryptogram.
Masked Token Number and PAR on Network Tokens
The network token object now carries the masked token number (TPAN) and the Payment Account Reference:network_token.masked_number, last_four, bin
and payment_account_reference. Guardian derives them from the token data it
already sees at provisioning and on the cryptogram path and stores only the
BIN, the last four digits and the PAR; the plaintext TPAN still never
leaves the card data environment. Tokens provisioned before this release
receive the digits with their next cryptogram, Mastercard tokens their PAR
through a backfill; each change is announced by a network.token.updated
webhook.List tokens accepts a
last_four filter, the first filter on that endpoint, and keeps it in the
pagination links. The admin token lookup shows the masked number and the PAR.
See Token Digits and PAR.Scheme Deletions Delete the Network Token
A network token the card scheme deletes is now deleted in Guardian exactly like one you delete through the API: it disappears from the token list and can no longer be read. Until now a scheme-side deletion only set the status todeleted, so the token stayed listed and you learned about it through a
network.token.updated webhook. Both kinds of deletion now send a dedicated
network.token.deleted webhook, so you no longer have to infer a deletion
from a status change.Forwards Go Only Where They Were Checked
Guardian resolves a forward’s destination once, checks that address, and sends the request to exactly that address. A hostname can no longer pass the check with a public address and then resolve to an internal one when the request is sent. The destination still receives its own hostname in theHost header, with the port when it is not the default, including
destinations reachable only over IPv6.Improvements and bugfixes
- A custom header pair (
x-own-header-name/x-own-header-value) can no longer setHostorContent-Length. Guardian sets both itself and drops a pair that names either. - A card number in
metadataoradditional_data, for example incardholder_name, is rejected on every tier, test cards included. - Endpoints that never take card data — such as sessions, forwards, and generic tokens — reject a request that carries a card number in any field, including a card number sent as an unquoted JSON number or as a query parameter.
Forwards Are Delivered at Most Once
Forwarding — card data, cryptogram, or wallet token — now guarantees at-most-once delivery to your destination. Guardian never retries a forward on its own: a payment authorization cannot reach your endpoint twice, and a failed forward is always yours to decide about. At the same time, the sporadic502 responses some integrations saw when a pooled connection to
the destination had gone stale are gone — Guardian discards idle
connections before that can happen, so the fresh guarantee does not come at
the cost of more transient errors.Improvements and bugfixes
- A session created with
expires_innow strictly caps the resulting token’s lifetime. Lifecycle arguments in the encrypted client payload — documented as ignored on such sessions — could previously extend a token’s expiry past the session’s TTL; they no longer can. See PCI Tokens for how session and client-side lifecycle settings interact. - Browser requests to the session endpoints now accept the Web SDK’s traceability headers, so cross-origin session calls carry full request tracing.
Forward Header Overrides and PCI Token Expiry in the Specification
The OpenAPI document now declares thex-own-header-name / x-own-header-value
header pair on all three forward operations — card data, cryptogram, and wallet
token. Guardian strips the credential your call authenticates with before
forwarding; the pair sets the destination’s own credential on the forwarded
request. The behavior is unchanged and was already described in the
PCI Tokens guide; clients
generated from the document alone could not send a destination credential
before.pci_token.expires_at is now typed nullable: a token created without an expiry
returns "expires_at": null, which a schema-validating client previously had
to reject.Documentation only; no endpoint changed. Regenerate clients.Data Classification Markers on Card Fields
The Guardian API reference now marks every field that carries regulated data.account_number and the PAN returned on a cryptogram are marked pci-pan;
security_code, the cryptogram itself, and the dynamic CVV are marked
pci-sad; cardholder_name is marked pii.The marker is a gate as well as a label: sending values into pci-pan or
pci-sad fields requires your PCI DSS certification on file at SAQ-D or a full
Report on Compliance. This is what makes the difference between the
session-based and direct-PAN integration paths visible field by field.Fields without a marker hold none of those categories — masked and truncated
card numbers are the common example. The
full legend
is on the API reference.Nothing about any endpoint changed — this is documentation only.Polymorphic Request Bodies Specified as Discriminated Unions
The request bodies that accept several shapes —source on PCI token creation,
network token creation, and metadata inquiry, plus the cryptogram request — are
now specified as discriminated unions on type. The accepted requests are
unchanged; what changes is that the specification states which type selects
which shape, so the reference documentation shows one tab per source and
generated clients get a proper tagged union.Three places where the specification was looser than the API and has been
corrected: type is required on the cryptogram request, and both type and
account_number are required on a metadata inquiry from a PAN. Requests
missing them were already rejected — the document simply did not say so.Responses that vary by shape rather than by a tag — PCI token creation, network
token creation, and the cryptogram response — keep their existing structure and
now document how to tell the variants apart.Richer Network Token Provisioning Events
network_token.provisioned events now carry the network_token_id, the
pci_token_id, and the card’s last_four, so you can reconcile provisioning
activity against your token records without extra lookups.Improvements and bugfixes
- Fixed access token verification: a valid OAuth2 access token could be
rejected with
401 invalid_token. See Authentication.
OAuth2 Access Tokens Replace API Keys
Guardian now authenticates with an OAuth2 access token, the same client-credentials flow used across the Hellgate Cloud Platform. Request a token from the Authentication API with your instance name as the audience, and send it asAuthorization: Bearer <access_token>. The scopes that previously sat on an
API key now travel in the token.Long-lived x-api-key credentials are deprecated. Existing integrations
keep working, but new ones should use access tokens. The x-admin-token
header has been replaced — administrative endpoints now accept the same
access token carrying the relevant admin:* scope. See
Authentication.Card Fingerprints on PCI Tokens
PCI token responses can now includecard.fingerprint: a deterministic,
non-reversible identifier of the card number, unique per Guardian instance.
The same card always produces the same fingerprint — across session and
pan tokenization and after a reissue with a new expiry date — so you can
recognize a returning card without handling the PAN. The field is read-only
and enabled per instance. See
PCI Tokens for
details.Simpler Apple Pay Domain Verification on Self-Managed Deployments
Onself_managed deployments, registering an Apple Pay domain now marks it
verified immediately: you attest domain ownership to Apple yourself by
registering the domain in the Apple Developer portal, where Apple fetches the
domain-association file you serve. Guardian no longer calls Apple during
registration on these deployments; only sf_operated deployments verify
domains against Apple’s Web Merchant Registration API in the background. See
Apple Pay
for the updated flow.Apple Pay Operating Modes and Settings
Guardian Apple Pay deployments now run in one of two modes. Inself_managed
mode (the default) you upload your own Apple identity and manage the
certificates yourself; in sf_operated mode Starfish operates the Apple
Developer relationship and mounts the identity and certificates for you, so
the settings-upload and certificate-management endpoints are disabled and
return 409 with the classifier APPLE_PAY_CERT_MANAGEMENT_UNAVAILABLE.Self-managed operators upload their Apple identity up front with the new
Update settings
endpoint (merchant_identifier, display_name, domain_association_content,
and csr_common_name), which Guardian reads when generating CSRs, serving the
domain-association file, and validating merchant sessions. See
Apple Pay for the full
setup.Wallet Tokens with Apple Pay
Guardian now accepts Apple Pay payments as wallet tokens. Pass the encryptedPKPaymentToken payload straight to Guardian, and it verifies the EC_v1
signature against Apple’s trusted certificates, decrypts, and stores the
device token server-side, so the decrypted card data never touches your
systems. Guardian also proxies Apple Pay merchant-session validation, so the
browser’s onvalidatemerchant exchange completes without you holding any
Apple certificates. From there you can forward the resulting
wallet token to your PSP
or acquirer. See Apple Pay
to get started.Apple Pay Certificate and Domain Management
Guardian now manages the credentials Apple Pay needs: it generates payment processing and merchant identity CSRs with the private keys held inside its PCI boundary, accepts the certificates Apple signs, tracks their lifecycle (pending, active, retired, disabled) with per-certificate audit
events, and registers and verifies the merchant domains that present the
Apple Pay button. See
Apple Pay
for the setup steps.Wallet Tokens with Google Pay
Guardian now accepts device wallet payments, starting with Google Pay. Pass the encrypted Google Pay payload straight to Guardian — it verifies the ECv2 signature chain, decrypts, and stores the credential server-side, so the decrypted card data never touches your systems. From there you can forward the resulting wallet token to your PSP or acquirer, and promote a card-on-file (PAN_ONLY) token to a full network
token. See Google Pay
to get started.JWT Authentication
A new JWT authentication lane runs in parallel to API keys. Guardian validates incoming tokens against your JWKS endpoint, letting you authenticate services with short-lived JWTs instead of, or alongside, long-lived API keys.Network Token Cryptogram Forwarding
You can now forward a network token cryptogram by reference onPOST /api/network/tokens/{id}/forward, so Guardian resolves the cryptogram
server-side and it never touches your systems. Forward templates also expose
more binds — including dynamic_cvv and additional network token fields — for
richer downstream requests.Token Lifecycle Controls
New token lifecycle controls let you set and manage expiration on stored tokens. Guardian accepts anexpiration_time alias for expires_in, and a
session’s expires_in now consistently takes precedence over the ephemeral
payload flag.Improvements and bugfixes
- Guardian now detects PANs in non-PAN attributes, catching card data that would otherwise slip through in the wrong field.
- Ingress forwarding headers are no longer relayed to destinations, keeping internal routing headers out of your outbound proxy requests.
- Network token create responses now serialize
pci_token_id. - Clearer proxy template errors: Guardian returns
422when a placeholder resolves to a map, validates unwrap placeholders inside multi-part templates, and gives more precise messages for non-renderable placeholders. - Ephemeral sessions without an
expires_inare handled correctly.
Guardian Admin UI
Guardian now ships with a built-in Admin UI for day-to-day token operations. Browse and manage tokens, handle API keys with proper timezone-aware expiration, and walk new operators through token creation — all backed by a Playwright end-to-end test suite so it stays solid release after release.Metadata Inquiry Endpoint
A newPOST /metadata/inquiry endpoint lets you look up issuer metadata
on-demand. The endpoint is feature-flagged per tier, propagates the
x-request-id end-to-end as a correlation ID, and emits a billing event
tagged with the requester’s contract ID — so reporting and chargeback
reconciliation work out of the box.Improvements and bugfixes
- American Express now renders with its proper scheme name in admin views.
- Metadata inquiry events include
network_token_idfor richer reconciliation data. - Hellgate SDK
<script>tag no longer carries SRI/crossoriginattributes, simplifying embedding.
Token Import
Migrating into Guardian from a legacy vault just got dramatically easier. A new admin Tokens Import workflow lets you bulk-load tokens via SFTP, with vault key handling that accepts both PEM and OpenSSH key formats. Move large token estates in hours, not weeks.Improvements and bugfixes
- Vault error handling is now much more informative — fewer mystery failures, more actionable messages.
- Clearer error response when creating a PCI token with invalid input.
Generic Token Types API
Building on January’s Generic Tokens launch, you can now manage token type definitions through a new admin API:GET /api/admin/types,
GET /api/admin/types/{id}, and DELETE /api/admin/types/{id}. Type
schemas are validated at token-creation time, and you can filter your
generic tokens by type_id — making it straightforward to organize
SEPA credentials separately from API keys, for example.Improvements and bugfixes
- PCI token limits are now checked before network tokenization, avoiding half-completed states when a tenant hits its cap.
- Network token status is validated before cryptogram creation, surfacing a clean error instead of an opaque failure deep in the cryptogram path.
- Token requestor returns proper user-facing error messages.
404response shape is now consistent across the API.- Completed sessions return a sensible response even when the network token attempt failed.
- Added PAYONE test cards to the test fixtures.
Introduction of Generic Tokens
Effecitve with this release, you can now store arbitrary payloads (for example SEPA credentials, API keys, or other sensitive data). Find more information in our documentation.Improved TMS Support
The integration of VISA Token Management Service (TMS) was update for better feature coverage and more flexibility.Added support for VISA Token Management Service (TMS)
Effecitve with this release another backend for network token management was added. This brings more options and better flexibility.Bugfixes
- Allow deletion of network tokens in case of active cryptograms.
- Better handling of image dimensions of card-art data.
- Better error messages for missing data in scheme cryptograms.