Skip to main content
PCI Tokens protect sensitive card payment credentials and keep raw card data out of your systems. This feature gets you out of the PCI compliance hassle in almost no time. Create tokens from a secure session (SAQ-A+) or by importing PAN data (SAQ-D+), depending on your compliance level.

​
Tokenizing Cards

There are two ways to tokenize a payment card, as described in the table below.

​
Token lifecycle

How long a token is retained is decided at creation time:
  • Persistent (default) — a token created without any lifecycle input is stored until you delete it via DELETE /api/pci/tokens/{id}.
  • expires_in — optional field on POST /api/pci/tokens, in seconds, between 1 and 2592000 (30 days). The token is deleted automatically once this time has passed. Creating a session with expires_in locks the session to ephemeral tokenization: the Web SDK receives a lifecycle: "ephemeral_only" hint in the session data, client-side lifecycle arguments are ignored, and the session’s TTL applies to the resulting token.
  • Client-side choice — a session created without expires_in runs in user_choice mode. The client may include ephemeral: true (delete after a short TTL, 15 minutes by default) or an explicit expiration_date (ISO-8601, in the future, at most 30 days ahead) in the encrypted payload; expiration_date takes precedence over ephemeral. When neither is sent, the token is persisted — the legacy behaviour, kept for backward compatibility with older SDK versions. See the Web SDK token lifecycle reference for the browser-side API.
  • Network tokens — sessions created via POST /api/network/tokens always produce persistent tokens (lifecycle: "persistent_only"); expires_in and client-side lifecycle arguments are not supported there.
An invalid expiration_date (not ISO-8601, or in the past) completes the session with status: "failure" and reason_code: "VALIDATION_ERROR". Automatic expiry removes the token the same way as an API deletion: the record is soft-deleted and the sensitive card data is scrubbed.

​
Using tokenized cards

The cards are stored securely in the Guardian vault. You cannot access the raw card data, but can use the token with other compliant third parties. A typical use-case is to send the card data to a payment service provider (e.g. an Acquirer) for processing. Guardian acts as a forwarding proxy: your request never contains raw card data. Guardian injects it on the way to the third party, so the PCI-relevant data stays out of your systems.

​
Injection of sensitive data

The endpoint to forward the card data is POST /api/pci/tokens/{id}/forward (see Forward card data for more details).. This feature forwards your request to the third party and will inject the sensitive data on the fly. You define where to put the data using placeholders. The following table shows the available options:

​
Unwrapping data

All injected data will be represented as a string in the payload. If a specific data type is required, such as a numeric representation of the expiry month, the data can be unwrapped and converted back to its original type as needed: {{ expiry_month | unwrap }}

​
HTTP Headers

Guardian forwards all headers from the request, except those it uses internally (e.g. x-api-key). To override these internal headers, you can provide a key-value pair that replaces the original header with your custom value. The following example demonstrates this situation, using the deprecated API key lane: the call to Guardian carries an API key in the header, and the destination requires another API key under the same header key. In this case you can use the x-own-header-name and x-own-header-value headers to override the original header. The same override applies to whichever header your call to Guardian authenticates with.
In the forwarded call, a header x-api-key: 123456... will be set, replacing Guardian’s internal x-api-key header.

​
Card Fingerprints

Every PCI token can carry a fingerprint in its card object — a deterministic, non-reversible identifier of the card number, prefixed with card_fp_. The same card always produces the same fingerprint on your instance, regardless of how it was tokenized, so you can recognize a returning card across channels (e.g. web and app) without handling the PAN.
Card fingerprints are enabled per instance. When disabled, the field is not part of token responses.
A few properties to be aware of:
  • The fingerprint is derived from the card number only. It does not change when a card is reissued with a new expiry date.
  • Fingerprints are scoped to your instance and cannot be compared across different Guardian instances.
  • Tokenization does not deduplicate: tokenizing the same card twice creates two tokens carrying the same fingerprint. Compare fingerprints on your side to detect duplicates.
  • The field is read-only. Tokens created before the feature was activated receive their fingerprint through a backfill shortly after activation; until then the field is null.