Pci Compliance

PCI DSS Compliance Coding Guidelines

1. Overview

PCI DSS (Payment Card Industry Data Security Standard) is a set of security requirements established by the major card brands (Visa, Mastercard, Amex, Discover, JCB) to protect cardholder data wherever it is processed, stored, or transmitted. Every developer writing code that touches payment card information -- whether directly handling card numbers or integrating with a payment processor -- must understand these requirements because a single coding mistake (logging a full card number, storing a CVV, transmitting over HTTP) can cause a data breach, result in fines ranging from $5,000 to $100,000 per month, and revoke the organization's ability to accept card payments entirely.

2. The 12 Requirements (Developer View)

3. Data Classification

3.1 NEVER Store (Prohibited Under All Circumstances)

These data elements must never be written to any persistent storage, log file, error message, analytics system, or debugging output after authorization:

• Full magnetic stripe data (track 1 and track 2)
• CVV / CVC / CID (3 or 4 digit security code)
• PIN or encrypted PIN block
• Full unmasked card number in logs or error messages

3.2 May Store (With Encryption and Business Justification)

Code examples: PAN masking functions, log sanitization regex patterns, and Luhn validation implementations in PHP, Python, and JavaScript are in resources/data-handling-patterns.md.

9. Scope Reduction

9.1 Hosted Payment Pages

The most effective way to reduce PCI scope is to never let card data touch your servers. Use hosted payment forms provided by your processor.

Stripe Elements (iframe approach):

<!-- Card fields are rendered inside a Stripe-hosted iframe -->
<!-- Your page never has access to the raw card data -->
<form id="payment-form">
    <div id="card-element">
        <!-- Stripe Elements iframe renders here -->
    </div>
    <button type="submit">Pay</button>
</form>

<script src="https://js.stripe.com/v3/"></script>
<script>
    const stripe = Stripe('pk_live_...');
    const elements = stripe.elements();
    const card = elements.create('card');
    card.mount('#card-element');

    document.getElementById('payment-form')
        .addEventListener('submit', async (e) => {
            e.preventDefault();
            const { token, error } = await stripe.createToken(card);
            if (token) {
                // Send token.id to your server -- not card data
                submitToServer(token.id);
            }
        });
</script>

Hosted Payment Page (redirect approach):

// Create a checkout session server-side, redirect the user
app.post('/api/create-checkout', async (req, res) => {
    const session = await stripe.checkout.sessions.create({
        payment_method_types: ['card'],
        line_items: [{ price: 'price_xxx', quantity: 1 }],
        mode: 'payment',
        success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
        cancel_url: 'https://example.com/cancel',
    });
    res.json({ url: session.url });
});
// User is redirected to Stripe's domain for card entry
// Card data never passes through your server

9.2 SAQ Types

Choose the approach that minimizes your compliance burden:

Decision rule: Always prefer SAQ A or SAQ A-EP. Only accept SAQ D scope if you have a specific business requirement to handle raw card data.

9.3 Network Segmentation

If you must process card data, isolate payment systems from the rest of your infrastructure:

Segmentation principles:
  - Payment processing services in a separate network zone
  - Firewall rules allowing only required traffic between zones
  - Payment database accessible only from payment services
  - No direct access from general application servers to payment data
  - Monitoring on all cross-zone traffic
  - Separate CI/CD pipeline credentials for payment services

10. Compliance Levels

PCI DSS defines four merchant levels based on annual transaction volume:

Note: Any merchant that has suffered a breach can be escalated to Level 1 regardless of transaction volume. Card brands may also independently assign levels based on risk assessment.

11. Common Mistakes

12. Quick Reference

DO

[x] Use payment processor tokenization (Stripe, Braintree, Adyen, Square)
[x] Mask PAN to first 6, last 4 digits in any display or log
[x] Encrypt stored cardholder data with AES-256-GCM
[x] Enforce TLS 1.2+ on all payment endpoints
[x] Set Secure, HttpOnly, SameSite=Strict on all cookies
[x] Implement RBAC on payment data endpoints
[x] Log all access to payment data with timestamp, user, IP, action, result
[x] Use parameterized queries for all database operations
[x] Validate input: Luhn check, expiry format, CVV length
[x] Return generic error messages; log details server-side with correlation IDs
[x] Rotate encryption keys at least annually
[x] Load secrets from environment variables or a secrets manager
[x] Clear sensitive data from memory after use
[x] Use hosted payment pages to minimize PCI scope
[x] Retain audit logs for minimum 12 months
[x] Use separate database credentials for payment services
[x] Apply Content-Security-Policy headers on payment pages
[x] Test that logs do not contain card numbers

DO NOT

[ ] Store CVV/CVC/CID after authorization -- ever
[ ] Store full magnetic stripe data or PIN blocks
[ ] Log full card numbers or sensitive authentication data
[ ] Hardcode encryption keys, API keys, or credentials in source code
[ ] Concatenate user input into SQL queries
[ ] Transmit card data over plain HTTP
[ ] Use MD5 or SHA-1 for "encrypting" card data
[ ] Return card data in API error responses
[ ] Disable TLS certificate verification in production
[ ] Use default or shared credentials for payment databases
[ ] Grant broad database permissions to payment service accounts
[ ] Skip audit logging on payment endpoints
[ ] Store PAN in plaintext
[ ] Use innerHTML to render payment-related user input in the browser
[ ] Allow card data to pass through your servers when tokenization is available

Resources