Logging must provide accurate, consistent, and actionable visibility into system behavior and transaction processing.

It must enable the Merchant to understand how the system operates under both normal and exceptional conditions, supporting troubleshooting, validation of execution flows, and post-incident analysis.

Scope of Logging

Logging must cover all relevant events across the transaction lifecycle.

• The Merchant system must log:
  • API requests and responses (at a metadata level)
  • Asynchronous notification reception and processing
  • Internal processing steps affecting transaction state
  • Error conditions and exceptional scenarios
• Logging must include both:
  • Successful operations
  • Failed or incomplete operations

Logging coverage must ensure that no critical step in the transaction lifecycle is unobservable or untraceable.

Structure and Consistency

Logs must be structured and consistent to support reliable interpretation and analysis.

• Each log entry must:
  • Follow a consistent format
  • Include clearly defined fields
  • Be machine-readable where possible
• Logs must include:
  • Timestamps
  • Event type or operation
  • Relevant identifiers (e.g., transaction ID, merchant reference)
  • Execution outcome

The structure and semantics of request and response fields are defined in F.2 Requests and Responses (Annotated), and must be used as the reference for determining which elements are relevant for logging.

Consistency in logging structure enables:

• Automated processing and monitoring
• Efficient troubleshooting
• Reliable correlation across system components

Context and Completeness

Logs must provide sufficient context to reliably reconstruct execution flows.

• Each logged event must include:
  • The relevant transaction or operation context
  • The relationship to preceding and subsequent events
• Logs must allow:
  • End-to-end reconstruction of transaction flows
  • Identification of execution paths and decision points

Incomplete or fragmented logging reduces the ability to diagnose issues and validate system behavior.

Logging of Requests and Responses

Logging of API interactions must balance observability with data protection.

• The Merchant system must:
  • Log request and response metadata
  • Capture key fields required to understand behavior and outcomes
• Logging must avoid:
  • Storing full payloads when not necessary
  • Exposing sensitive or confidential information

Where deeper inspection is required for troubleshooting:

• Controlled and sanitized logging approaches must be used
• Temporary debug logging must not introduce security risks

The structure and meaning of the fields captured in requests and responses must be interpreted according to F.2 Requests and Responses (Annotated).

Handling of Errors and Exceptional Scenarios

Errors and exceptional conditions must be explicitly logged.

• The Merchant system must:
  • Log all error responses and failure conditions
  • Capture relevant diagnostic information
  • Distinguish between:
    • Technical errors
    • Business-level outcomes (e.g., declined transactions)
    • Indeterminate states (e.g., timeouts)

These categories align with the interpretation model defined in F.3 Success and Error Scenarios, and must be consistently reflected in logging practices.

Clear logging of errors enables:

• Accurate classification of issues
• Controlled retry and recovery strategies
• Faster root cause analysis

Security and Data Protection in Logging

Logging must be implemented in a manner that preserves security and data confidentiality.

• Sensitive data must:
  • Never be logged in clear form
  • Be masked or omitted when necessary
• Logs must not expose:
  • Authentication credentials
  • Tokens or secret values
  • Payment data

Sensitive data handling in logs must comply with the data protection controls defined in F.4.2 Data Protection and Exposure.

Logging must balance observability and security, ensuring that operational visibility does not introduce new risks.

Reliability and Availability of Logs

Logging systems must be reliable and consistently available.

• The Merchant system must ensure that:
  • Logging failures do not disrupt core transaction processing
  • Logs are persisted reliably
  • Logging is consistently applied across all components

Loss of logs or inconsistent logging may result in gaps in visibility and hinder troubleshooting and audit processes.

Key Principle

Logging must be designed as a foundational system capability, ensuring that all relevant events are captured in a structured, consistent, and secure manner, enabling accurate interpretation of system behavior under real-world conditions.