How to use this tool

Cardholder Data Flow — Guide

How to visualise and analyse the flow of cardholder data through your payment architecture, determine CDE scope, and export a PCI DSS security brief.

What is this tool for?

PCI DSS Requirement 12.3.1 requires you to maintain an accurate diagram of all cardholder data flows — where card data enters your environment, how it moves between systems, and where it exits. This diagram must be reviewed and updated at least annually.

This tool generates an interactive data flow diagram for four common payment flow types, configurable by gateway, tokenisation approach, and CDE scope. Each component is annotated with its security controls, zone classification, and PCI DSS requirement references. Export the full analysis as a security brief.

Step-by-step walkthrough

Step 1 — Configure your stack
  1. Select your payment gateway: Stripe, Adyen, Braintree, or Worldpay.
  2. Select your tokenisation approach: Hosted Fields, Network Tokenisation, In-house Vault, or None.
  3. Select your CDE scope: Minimal (gateway-hosted), Standard (gateway + internal API), or Full (includes database and downstream services).
Step 2 — Select a flow type
  1. Choose from Standard Checkout, Agent-Initiated Payment, Refund Flow, or Webhook Processing.
  2. The diagram updates to show the step-by-step flow for that transaction type, with components coloured by zone.
Step 3 — Inspect components
  1. Click any component in the flow to expand its detail panel, showing security controls, zone classification, and PCI DSS requirement references.
  2. Components shaded in the CDE colour are in-scope for PCI. Out-of-scope components are shown in a dimmer shade.
Step 4 — Export the security brief
  1. Click Export Brief to download the full flow analysis as a Markdown document.
  2. The brief includes: flow overview, CDE scope analysis, per-component security controls, and PCI DSS requirements coverage matrix.
  3. Use it as a data flow diagram supplement in your QSA audit package (required by PCI DSS Req 12.3.1).

Security zones explained

Public Zone
Internet-accessible components: browser, CDN, WAF, API Gateway. Out of PCI scope if no cardholder data passes through in cleartext.
Application Zone
Internal VPC components: payment service Lambda/ECS, fraud checker, webhook handler. In PCI scope — these components process payment intents and may handle tokenised card data.
Data Zone
Storage and data services: DynamoDB, Aurora, KMS, Secrets Manager. In PCI scope — key stores and databases containing payment records.
Gateway Zone
External payment gateway systems: Stripe, Adyen, Worldpay. Out of your direct PCI scope (gateway is responsible) but the API call is in scope for transit encryption requirements.
Connected-to-in-scope rule: If a system is network-connected to a CDE component, it may also be in-scope even if it doesn't handle cardholder data directly. Consult your QSA to confirm scoping for connected systems.

Flow types explained

Standard Checkout
Browser → CDN/WAF → API Gateway → Payment Service → Fraud Check → Gateway SDK Call → DynamoDB write → webhook confirmation. The baseline flow for most card-present and card-not-present e-commerce payments.
Agent-Initiated Payment
Agent triggers payment intent → Lambda validates → KMS decrypt credentials → Gateway SDK → Step Functions saga → DynamoDB idempotency check → SQS confirmation. The flow for autonomous agent payment execution.
Refund Flow
Refund request → auth check → Gateway refund API → Ledger reversal → Receipt email. Shorter than the forward payment flow but includes the same PCI scope for gateway and ledger components.
Webhook Processing
Inbound webhook → signature verification → SQS enqueue → Lambda consumer → DynamoDB idempotent update → event bus publish. Decoupled from the payment path for reliability.

Key terms

CDECardholder Data Environment — the systems that store, process, or transmit cardholder data (PANs, CVVs, expiry dates) and any systems connected to them.
PANPrimary Account Number — the 16-digit card number. The presence of PANs in a system is the primary determinant of CDE scope.
Hosted fieldsA tokenisation approach where the payment gateway renders the card input fields in an iframe. PANs are submitted directly to the gateway and never transmitted to your servers.
Network tokenA PAN substitute issued by Visa (VTS) or Mastercard (MDES) that can be used for recurring payments. The original PAN is stored by the card network, not by you.
Data flow diagramA diagram required by PCI DSS Req 12.3.1 showing how cardholder data enters, moves through, and exits your environment. Must be reviewed annually.
SegmentNetwork isolation between in-scope CDE systems and out-of-scope systems. Proper segmentation is the most effective way to reduce PCI scope.

Frequently asked questions

Ready to map your cardholder data flows?
Configure your gateway and tokenisation approach, select a flow type, and export a PCI DSS security brief.