PCI Token Export

You can request an export of PCI tokens that are stored on our systems. Requests are performed only after review and approval. Once approved, the resulting dataset is delivered as a PKI-encrypted .tgz archive via a time-limited download link to the requesting party.

Prerequisites

Certificate Requirements

For encryption, you must provide an X.509 certificate (PEM) containing the recipient’s public key. We accept recipient certificates only if all of the following criteria are met:

Requirement	Details
Certificate type	X.509 with OV or higher validation
Organization identity	Subject includes at least `O` (Organization) and `C` (Country)
Trust anchor	Issued by an approved public CA or an agreed private PKI
Validity	Certificate is within its validity period
Revocation status	Not revoked (CRL / OCSP or equivalent checks)
Key usage	Suitable for encryption

Use a dedicated certificate and key pair specifically for token export decryption, separate from TLS or general-purpose certificates.

Step-by-Step Process

Step 1 – Submit an export request

Submit an export request via your designated contact channel including:

Legal organization name
Cluster ID
Intended use case of the exported data
Attestation of PCI compliance
Scope (time range, system/batch, filters)
Recipient (team/service and responsible contact)
Point of contact for follow-up questions

Use a dedicated certificate and key pair specifically for token export decryption, separate from TLS or general-purpose certificates.

Step 2 – Provide the recipient OV certificate

Provide your recipient certificate in PEM format (Base64, including header and footer). The certificate must contain the public key used for encryption.

Never send private keys, passphrases, or HSM access details.

Step 3 – Review and approval

We perform two independent checks:

Certificate validation: trust chain, validity period, revocation status, key usage / extended key usage, and organizational identity
Authorization review: intended use, contractual scope, and applicable compliance requirements

Once all checks are successfully completed, the export is approved and scheduled. If any issues are identified, we will contact you with specific remediation steps.

Step 4 – Export and PKI encryption

After approval, the dataset is exported from the relevant system and packaged as a compressed .tgz archive. The archive is then encrypted using your provided OV certificate.

Only the holder of the corresponding private key can decrypt the exported archive.

Step 5 – Delivery via download link

The encrypted .tgz archive is made available via a download link sent to the requester (or the designated contact specified in the request).The download link is:

Time-limited (expiration communicated separately)
Auditable (request ID, timestamp, delivery record)

Step 6 – Download, decryption, and internal handling

Download the encrypted archive and perform decryption and extraction using your internal tooling and security controls.

Decryption, validation, and secure processing of the exported data are the responsibility of the receiving organization.

Confirm that decryption succeeds, that the dataset matches the requested scope, and that internal controls for handling the data are in place before wider distribution.

Step 7 – Storage and retention

Store and process the decrypted dataset in accordance with:

Your internal security policies
Applicable regulatory and compliance requirements
Contractually agreed retention and deletion rules

Export Data Format

The exported .tgz archive contains a manifest JSON file and encrypted JSONL records containing the PCI token data.

export-<export-id>.tgz
├── manifest.json
└── tokens.jsonl.enc

Encryption Details

The export uses a hybrid encryption scheme:

AES encryption is used to encrypt the JSONL records file
The AES key is encrypted using RSA-OAEP-256 with your provided OV certificate’s public key
The encrypted AES key, initialization vector (IV), and authentication tag are stored in the manifest

Manifest Format

The manifest.json file contains metadata about the export and encryption parameters:

{
  "version": "1.0",
  "export_id": "<uuid>",
  "created_at": "2025-01-15T10:43:00Z",
  "guardian_instance": "my-cluster-id.on-hellgate.cloud",
  "encryption": {
    "algorithm": "RSA-OAEP-256",
    "recipient": {
      "subject": "O=Acme Payments GmbH, C=DE",
      "issuer": "CN=DigiCert TLS RSA4096 Root G5, O=DigiCert Inc, C=US",
      "serial": "0f:4a:2b:...",
      "fingerprint": "sha256:3c:5d:8e:..."
    },
    "encrypted_key": "<base64>",
    "iv": "<base64>",
    "tag": "<base64>"
  },
  "content": {
    "record_count": 142857,
    "checksum": "sha256:<hex>"
  }
}

Field	Description
`version`	Export format version
`export_id`	Unique identifier for this export
`created_at`	Timestamp when the export was created
`guardian_instance`	The Guardian instance identifier
`encryption.algorithm`	The RSA encryption algorithm used (`RSA-OAEP-256`)
`encryption.recipient.subject`	Certificate subject (organization identity)
`encryption.recipient.issuer`	Certificate issuer (CA)
`encryption.recipient.serial`	Certificate serial number (hex)
`encryption.recipient.fingerprint`	Certificate fingerprint (SHA-256)
`encryption.encrypted_key`	AES key encrypted with recipient’s public key
`encryption.iv`	Initialization vector for AES encryption
`encryption.tag`	Authentication tag for AES-GCM
`content.record_count`	Total number of records in the export
`content.checksum`	SHA-256 checksum of the decrypted JSONL content

Record Format

The records.jsonl.enc file contains encrypted JSONL (JSON Lines) data. After decryption, each line is a JSON object representing a PCI token record. Each record follows the PCI token payload structure with the following differences:

The account_number field contains the unmasked full account number (instead of masked_account_number)
All other fields match the standard PCI token API response format
Metadata is included if present

{
  "id": "8744c9ea-a02b-4ae6-875c-b64fc333e3ef",
  "card": {
    "cardholder_name": "John Doe",
    "expiry_month": 12,
    "expiry_year": 2025,
    "account_number": "4111111111111111",
    "scheme": "visa"
  },
  "created_at": "2023-10-01T12:00:00Z",
  "expires_at": "2025-10-01T12:00:00Z",
  "metadata": {
    "my_key_one": "my_value_one",
    "my_key_two": "my_value_two"
  }
}

Decryption Process

To decrypt the export:

Extract the .tgz archive
Read manifest.json to obtain encryption parameters
Decrypt the AES key using your private key
Use the decrypted AES key, IV, and tag to decrypt records.jsonl.enc
Verify the checksum in the manifest matches the decrypted content
Process the JSONL file line by line (each line is a complete JSON object)

Common Issues & Troubleshooting

We only have a public key, not a certificate.

A raw public key without a CA-issued certificate cannot be accepted. Please provide an OV (or higher) X.509 certificate containing the public key.

Our certificate is Domain Validated (DV).

DV certificates do not provide organizational identity validation and are therefore not sufficient. Please use an OV or EV certificate.

The download link has expired.

Submit a new request referencing the original request ID. A new link can be issued after any required re-validation.

Getting Started

Features

Management

Migrations

Prerequisites

Certificate Requirements

Step-by-Step Process

Export Data Format

Encryption Details

Manifest Format

Record Format

Decryption Process

Common Issues & Troubleshooting

​Prerequisites

​Certificate Requirements

​Step-by-Step Process

​Export Data Format

​Encryption Details

​Manifest Format

​Record Format

​Decryption Process

​Common Issues & Troubleshooting

Prerequisites

Certificate Requirements

Step-by-Step Process

Export Data Format

Encryption Details

Manifest Format

Record Format

Decryption Process

Common Issues & Troubleshooting