Logging, Data Masking and Audit Trails for Payments

Payment systems need two kinds of records that pull in opposite directions: enough detail to investigate any transaction months later, and strict limits on the sensitive data those records contain. Good logging answers "what happened and when" for every instruction; good masking ensures the answer never exposes card numbers, bank accounts or identity numbers to anyone who does not need them.

In South Africa this is shaped by two frameworks: PCI DSS for cardholder data and POPIA for personal information generally. Both apply to logs just as much as to databases.

What should you log for every payment?

For each instruction, mandate and status change, record:

• Your unique reference and the provider's or bank's reference
• Timestamps for every submission, acknowledgement and status change
• The channel used: API endpoint and message ID, or file name and record number
• Each status transition with its reason code and source
• Webhook events received, including delivery attempts and de-duplication decisions
• The credential or system identity that performed each action

This is what makes stuck payment investigations and reconciliation breaks resolvable in minutes instead of days.

What must be masked in logs?

Card data (PCI DSS)

The full primary account number (PAN) may not appear in logs. Standard practice:

• Truncate the PAN when displayed or logged, showing at most the first six and last four digits.
• Tokenise where a persistent card identifier is needed, storing the token rather than the PAN.
• Never log the CVV, full magnetic stripe data or PIN under any circumstances; PCI DSS prohibits storing these even encrypted.

The requirements are covered in PCI DSS, and the mechanics of tokenisation in tokenisation, encryption and hashing.

Personal information (POPIA)

Bank account numbers, South African ID numbers, passport numbers and contact details are personal information. In logs and error messages:

• Mask bank account numbers, showing only enough digits to distinguish records.
• Mask ID numbers; they are especially sensitive because they encode date of birth.
• Keep unmasked values in the systems designed to hold them, with access control, not in application logs, crash reports or third-party monitoring tools.

Where masking commonly fails

• Raw request and response bodies logged verbatim on errors
• Debug logging left enabled in production
• Stack traces and exception messages containing input data
• Log shipping to external tools without field-level filtering

Mask at the point of logging, with a shared sanitisation layer, rather than trusting every developer to remember.

What makes an audit trail different from a log?

A log records events for troubleshooting; an audit trail is an authoritative, tamper-evident history intended as evidence. For payments the critical audit trails are:

• Mandate history: creation, the exact terms accepted, authentication outcomes, amendments, suspensions and cancellations. When a debit order is disputed, you must be able to produce the mandate and its full history to defend the collection.
• Instruction history: every submission and status change, with references linking resubmissions to the original instruction.
• Administrative actions: who changed configuration, credentials, webhook URLs or mandate records, and when.

Audit trails should be append-only: corrections are new entries, never edits to old ones. Retain them for the period your bank, sponsor and regulators require, which for mandate-related records is typically measured in years after the last transaction.

Practical checklist

• One correlation reference carried through every log line for a transaction
• Centralised, searchable log storage with access control and retention policies
• A sanitisation layer that truncates PANs and masks account and ID numbers before write
• Append-only audit tables for mandates, instructions and admin actions
• Periodic sampling of production logs to catch masking regressions
• Clock synchronisation across systems so timelines are trustworthy

Back to the Payment Operations hub.