Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

This PR introduces the capability to send the Merchant Order Reference ID to the Unified Connector Service (UCS) as part of gRPC request headers. This enhancement allows the UCS to be aware of the merchant's original identifier for a transaction, which can be crucial for tracking, reconciliation, and reporting purposes.

Key Changes:

1. New UcsReferenceId Type:

   • Added a new enum UcsReferenceId in crates/common_utils/src/ucs_types.rs. This type can represent either a PaymentReferenceId or a RefundReferenceId, providing a unified structure for reference IDs in UCS communications.
   • Includes a get_string_repr() method for easy string conversion.

2. gRPC Header Enhancement:

   • Modified GrpcHeadersUcs in crates/external_services/src/grpc_client.rs to include an optional merchant_reference_id field of type UcsReferenceId.
   • Updated the corresponding builder types to support this new field.
   • A new gRPC header constant, UCS_HEADER_REFERENCE_ID ("x-reference-id"), has been added in crates/external_services/src/lib.rs to transmit this ID.

3. Integration in Payment Flows:

   • Authorize & Repeat Authorize Flows: The merchant_order_reference_id is now parsed from the request, validated, and wrapped in UcsReferenceId::Payment before being added to the UCS gRPC headers.
   • External Vault Proxy Flow: The merchant_order_reference_id is directly mapped and sent to UCS.
   • Other flows like Payment Sync (psync_flow) and Setup Mandate (setup_mandate_flow) have been updated to explicitly set merchant_reference_id to None in their UCS headers, maintaining consistency.

4. Data Type and Transformer Updates:

   • The merchant_order_reference_id in ExternalVaultProxyPaymentsData (hyperswitch_domain_models) is now strongly typed as Option<id_type::PaymentReferenceId> instead of Option<String>.
   • Transformers have been updated to correctly handle the new UcsReferenceId type, ensuring the string representation is used when constructing payloads for UCS.

Additional Changes

• This PR modifies the API contract (internal gRPC headers to UCS)
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Motivation and Context

By providing the UCS with the merchant's original order reference ID, we enable better traceability and linking of transactions between the merchant's system and Hyperswitch/UCS. This is a foundational step for features that might rely on this identifier for enhanced customer support, detailed analytics, or streamlined reconciliation processes within the UCS.

How did you test it?

Verified is the headers send from Hyperwitch are included in UCS events.

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible