How PCI Proxy Works
A technical yet accessible guide to the data flow, tokenisation engine and API-first architecture that keeps card data out of your infrastructure and your business out of PCI scope.
End-to-End Data Flow
From the moment a cardholder enters their PAN to the point your application receives a secure token, here is every step the data passes through.
Card Data Source
Browser checkout, REST API call or call centre agent IVR input
PCI Proxy Interception
The reverse proxy detects and extracts the 16-digit PAN from the HTTP payload
Tokenisation Engine
The PAN is encrypted (AES-256) and a unique format-preserving token is generated
Secure Vault
Original PAN stored in a PCI DSS Level 1 certified data centre with HSM inside the EU
Token Returned
Your application receives a secure token - use it for payments, subscriptions or refunds
The Tokenisation Process
Tokenisation replaces sensitive card data with a non-sensitive surrogate value. Here is exactly how PCI Proxy EU performs this operation - step by step.
Phase
PAN Detection
The proxy inspects incoming HTTP bodies with pattern-matching engines optimised for all major card schemes. Luhn-validated 13–19 digit sequences are flagged - across JSON, XML, form-encoded and multipart payloads. Zero code changes on your side.
Phase
Token Format
Every token follows a deterministic structure: a prefix (tok_pci_eu_) followed by a cryptographically random 30-character string. It carries metadata - last four digits, brand, expiry - allowing your UI to display "Visa ending in 1234" without ever accessing the real PAN.
Phase
One-to-One Mapping
Each PAN maps to exactly one token within your merchant namespace. The same card submitted twice returns the same token - enabling deduplication, fraud detection and card-on-file matching. The mapping is stored only in the vault and is never exposed via API.
→ Incoming POST /v1/tokenize
{
"card_number": "4111 1111 1111 1234",
"expiry": "12/26"
}
← Response 200 OK · 47ms
{
"token": "tok_pci_eu_a1b2c3d4e5f61234",
"last_four": "1234",
"brand": "visa",
"pan_in_your_systems": false
}
Retrieving the Original Card Data
De-tokenisation is the controlled, audited process of replacing a token with the original PAN - and it occurs exclusively within PCI Proxy's secure environment.
When It Occurs
De-tokenisation occurs only when a downstream PSP or acquirer requires the real PAN to authorise a transaction. Your system sends the token to PCI Proxy's forward-proxy endpoint; the proxy resolves the PAN internally and forwards it to the PSP over a mutually authenticated TLS connection. The PAN never appears in your logs.
Who Can Request It
Only API keys authenticated with the detokenize permission scope can trigger a de-tokenisation. Access is granted per-merchant, per-environment and can be restricted by IP whitelist and configurable rate limits.
Complete Audit Trail
Every de-tokenisation event is logged with timestamp, requesting API key, destination PSP, source IP and request ID. Logs are retained for a minimum of 12 months and are available through the merchant dashboard and audit API. Immutable, tamper-proof.
Security Layers
Rotating secrets, signed requests
Access restricted to known server IPs
Certificate-pinned connections to PSP
Tamper-proof, retained ≥ 12 months
API-First Architecture
A single RESTful JSON API. Authenticate with your key, send card data, receive tokens. Below are the two primary endpoints you will use daily.
/v1/tokenize Scope: tokenize Request Body
{ "card_number": "4111111111111111", "expiry": "12/26", "cvv": "123" }
Response 200 OK
{ "token": "tok_pci_eu_a1b2c3d4e5f6", "last_four": "1111", "brand": "visa", "expires_at": "2026-12-31" }
/v1/forward Scope: forward Request Body
{ "token": "tok_pci_eu_a1b2c3d4e5f6", "target_url": "https://psp.eu/charge", "amount": 9900, "currency": "EUR" }
Response (from PSP, proxied)
{ "status": "authorized", "transaction_id": "txn_9f8e7d6c", "amount": 9900, "currency": "EUR" }
Webhooks and Callback Flows
PCI Proxy EU sends real-time event notifications to your registered webhook endpoints. Each event includes a cryptographic signature you can verify server-side.
Webhooks use exponential backoff with up to 5 retries. Failed deliveries are stored for 72 hours and can be replayed from the dashboard.
Supported Event Types
token.created New token generated token.used Token forwarded to PSP token.expired Token reached its TTL token.deleted Token removed on request forward.success PSP returned 2xx forward.failure PSP returned error Webhook Payload Example
your-server.com/webhooks/pci LIVE
{
"event": "token.created",
"timestamp": "2026-04-03T10:15:30Z",
"data": {
"token": "tok_pci_eu_a1b2c3d4e5f6",
"last_four": "1111",
"brand": "visa",
"merchant_id": "mrc_xyz789"
},
"signature": "sha256=4a8b9c..." // HMAC-SHA256
}Signature Verification
Every webhook includes the X-PCI-Signature header. Compute HMAC-SHA256 of the raw body with your webhook secret and compare it against the signature value. Reject requests where signatures do not match.
SDK and Integration Options
Official SDKs in 5 languages, hosted fields and iFrame injection - choose the method that best fits your stack.
JavaScript SDK
npmimport PCIProxy from '@pci-proxy-eu/js';
const pci = new PCIProxy({
merchantId: 'mrc_xyz789'
});
const { token } = await pci.tokenize({
cardNumber: '4111...'
});Python SDK
PyPIfrom pci_proxy_eu import Client
client = Client(
merchant_id="mrc_xyz789",
api_key="sk_live_..."
)
result = client.tokenize(
card_number="4111..."
)PHP SDK
Composeruse PCIProxyEU\Client;
$client = new Client(
merchantId: 'mrc_xyz789',
apiKey: 'sk_live_...'
);
$result = $client->tokenize([
'card_number' => '4111...'
]);Hosted Fields and iFrame Injection
For SAQ A eligibility. Fields are rendered in secure iFrames - card data never touches your DOM.
<div id="card-number"></div>
<div id="card-expiry"></div>
<div id="card-cvv"></div>
<script>
PCIProxy.hostedFields({
merchantId: 'mrc_xyz789',
fields: {
cardNumber: '#card-number',
expiry: '#card-expiry',
cvv: '#card-cvv'
},
onTokenize: (result) => {
// token only, never the PAN
console.log(result.token);
}
});
</script>Payment Details
Card data never reaches your server
SAQ A
Minimum scope
CSS API
Customisable
Mobile
Responsive
Start Integrating Today
Discover what a PCI Proxy is, dive deeper into tokenisation details or see how developers use the platform.