Message Logging

Overview

The message logger enables clients to trace all messages related to a specific request, providing transparency for monitoring and audit purposes.

The VoP Requester logs the following messages:

  • Incoming Request/Response

  • CSM Reachability Deconstruct IBAN Request/Response

  • RVM Request/Response [1]

The below diagram depicts the message logs to and from the services, using FPAD as the selected RVM.

overview

How It Works

VoP Requester captures all messages exchanged with external systems:

  1. Message Capture: Messages are intercepted at key points in the processing flow and logged using the IPF Message Logger

  2. Message Structure: Each logged message contains:

    • Timestamp - when the message was logged

    • Processing context - contains request ID and processing entity

    • Message type - identifies the type of message (e.g., PROCESSING_ENTITY_VOP_REQUEST)

    • Direction - whether the message was SENT or RECEIVED

    • Message body - the actual content of the message (serialized to JSON)

    • Message ID - unique identifier linking related messages. Consists of three parts delimited by |

      • MESSAGE_LOG prefix

      • Request ID - The service generates a unique identifier for each request received from a processing entity. This identifier is included in this part of the Message ID and can be used for correlation, as described in point 3. All related messages will share the same value for this portion of the Message ID.

      • Random UUID - this part of the Message ID is unique for each message

    • Supporting data - additional metadata such as headers

  3. Message Correlation: All messages associated with a single transaction are tied together using the request ID from the incoming request. This enables straightforward tracing of the request throughout the system. The same request ID will also be included in the response.

Logged messages conform to the following JSON Schema

Message Retrieval

If Kafka message logging is enabled, message log entries will also contain Kafka Headers.

Currently, VoP populates the following values into the headers:

  • ipf_processing_context_client_request_id - The request ID as generated by the VoP Requester service.

  • ipf_processing_context_processing_entity - The processing entity received from the request message.

Other headers may be present as populated by the Connector Framework.
requestId and processingEntity headers are now deprecated and support for these fields will be removed from 2025.4.0.

If Mongo message logging is enabled, the equivalent fields to query on are:

  • processingContext.clientRequestId

  • processingContext.processingEntity

Configuration

The type of message logger to use is configured with the message.logger.type (default: kafka) property as documented in the applicable message logger configuration pages below (e.g. Kafka/Mongo)

  • Details of configuration options for the Kafka Message Logger are available here

  • Details of configuration options for the Mongo Message Logger are available here

Error Handling

The message logging system in VoP Requester is designed to be resilient to failures, ensuring that issues with message logging do not impact the core functionality of the service.

Runtime Errors

When errors occur during message logging, the following error handling mechanisms are in place:

  1. Resilient Error Handling: Errors in message logging are caught and logged but do not interrupt the main processing flow. This ensures that even if message logging fails, the primary service functionality continues to operate.

  2. Error Logging: When a message logging operation fails, an error message is logged with the request ID for traceability:

    • For request logging failures: "Error saving request to message logger"

    • For response logging failures: "Error saving response to message logger"

  3. Graceful Degradation: When Kafka message logging is enabled but Kafka becomes unavailable, the service remains operational. In this case, message logging is temporarily suspended until Kafka connectivity is restored. This behavior is managed using a circuit breaker mechanism configured within the message logging connector. For more information on circuit breakers, see here.

If Mongo is selected for message logging, and Mongo becomes unavailable after the VoP Requester has started, then the VoP Requester service will become unavailable.
1. When communication is direct between Payment Service Providers (PSPs) and an RVM is not used, the Responder Request/Response is logged instead.