Skip to main content
Version: v2

Enterprise Wallet Upgradation

Quick Reference
  • Purpose: Upgrade local merchant wallets to enterprise wallets with enhanced identification
  • Key Mechanism: Uses enterpriseResponseSearchPath with JSONPath to extract identifiers
  • Process Flow: Customer identification → Enterprise search → Extract values → Update wallet metadata
  • Configuration: Set appropriate merchantMetadataKey and precedence values for reliable matching
  • Upgrade Paths: Standard (direct MCID match) and Advanced (via enterpriseResponseSearchPath)
  • Key Benefit: Seamless experience across merchants without customer needing to create new wallets

Overview​

Enterprise Wallet Upgradation is a critical feature that allows local merchant-specific wallets to be enhanced with enterprise-level information. This capability creates a seamless customer experience by automatically upgrading existing local wallets to enterprise wallets when additional identification becomes available, without requiring any customer action.

Business Impact

By automatically upgrading local wallets to enterprise wallets, CCG can offer a consistent experience across different merchants while preserving customer payment history. This increases customer satisfaction and reduces friction during subsequent visits.

How Wallet Upgradation Works

When a customer interacts with a merchant system through the wallet service, the system can upgrade a local merchant-specific wallet to include enterprise-level information. This process involves:

  1. Identifying the customer using configured search criteria
  2. Finding the customer in enterprise identity systems
  3. Extracting additional identifiers from the enterprise response
  4. Using these identifiers to enhance the local wallet

The upgrade happens without any disruption to the customer experience, preserving all payment methods and transaction history.

Complete Configuration Example
{
  "customerSearchCriteria": [
    {
      "value": {
        "sourceCode": "CSP_Facets",
        "dependentCode": "xxxx"
      },
      "merchantSearchKey": "$.metadata.dependentCode",
      "enterpriseSearchKey": "identifiers.payer_memberId",
      "enterpriseValueKey": "dependentCode",
      "merchantMetadataKey": "dependentCode",
      "enterpriseResponseSearchPath": "$.[*].identifiers.payer_memberId[*]['dependentCode']",
      "precedence": 1,
      "required": true
    }
  ]
}

In this example:

  • merchantSearchKey: Extracts dependentCode from customer request
  • enterpriseSearchKey/enterpriseValueKey: Used for initial identity search
  • enterpriseResponseSearchPath: Used to extract dependentCode from all payer_memberId entries in the response
    • The enterpriseResponseSearchPath field is a JSONPath expression that defines where to look for specific values in the enterprise identity response. Unlike enterpriseSearchKey (which uses dot notation), enterpriseResponseSearchPath uses full JSONPath syntax for more powerful querying capabilities.
  • merchantMetadataKey: Specifies where to store the extracted value in merchant metadata

Wallet Upgrade Process​

Upgrade Process Flow
  1. Customer is identified in enterprise systems using configured search criteria
  2. System retrieves all CustomerSearchCriteria with configured enterpriseResponseSearchPath
  3. For each criterion, values are extracted from the enterprise response using enterpriseResponseSearchPath based on precedence
  4. Values are stored in metadata using the keys specified in merchantMetadataKey
  5. If a local wallet is found in CCG, it's upgraded to an enterprise wallet, preserving all payment methods and history
Detailed Wallet Upgrade Sequence

Upgrade Paths​

Understanding the Two Wallet Upgrade Paths

The wallet upgrade process supports two distinct paths for upgrading local wallets to enterprise wallets:

  1. Standard Upgrade Path (StandardUpgradeLocalWallet):

    • Triggered when a customer returns with the same MCID they used before
    • The MCID in the customer identification request directly matches an existing local wallet
    • Since the previous visit, this MCID has been associated with an enterprise record in EIMP
    • Example: Customer returns to merchant with same patientID, which now has a matching enterprise record

  2. Advanced Upgrade Path (UpgradeLocalWallet):

    • Triggered through the more complex search criteria processing
    • Uses enterpriseResponseSearchPath to extract additional identifiers from enterprise responses
    • Handles more complex matching scenarios where direct MCID matching isn't sufficient
    • Example: Customer identified via one MCID type but matched through a different identifier extracted from the enterprise response
Both paths ultimately result in the local wallet being upgraded to an enterprise wallet, with all existing payment methods and transaction history preserved.
Multiple Fallback Scenarios

The system supports multiple fallback sets through the precedence field at the CustomerSearchCriteria level:

  • The system first tries to identify customers using the criteria set with the lowest precedence value
  • If identification fails, it falls back to the next set based on precedence
  • Within each set, the system extracts values using enterpriseResponseSearchPath if configured

Example: A merchant might configure one set for dependentCode+subscriberId, and a fallback set for healthInsuranceExchangeId.

Use Cases​

PatientID Wallet Evolution​

When a customer initially interacts with a merchant using only patientID, a local wallet is created. On subsequent visits, if new enterprise information becomes available in EIMP for that patientID, the local wallet is automatically upgraded to an enterprise wallet, preserving all payment methods and transaction history while enabling enterprise-wide capabilities.

PatientID Wallet Evolution Example

Initial Visit (Local Wallet Creation):

  1. Customer visits a healthcare provider and is identified only by patientID
  2. CCG attempts to find an enterprise match using patientID but no match is found in EIMP
  3. CCG creates a local wallet for the customer using patientID
  4. Customer adds payment methods and completes transactions

Subsequent Visit (Wallet Upgrade):

  1. Same customer returns to the healthcare provider and is identified by the same patientID
  2. In the meantime, the customer's enterprise record has been created or updated in EIMP with this patientID
  3. During identification:
    • CCG finds the existing local wallet using patientID
    • CCG also now finds a match in EIMP using the same patientID
    • CCG extracts additional enterprise identifiers (enterpriseId, subscriberId, etc.)
  4. CCG upgrades the local wallet to an enterprise wallet by:
    • Associating it with the enterpriseId
    • Adding extracted identifiers to merchant_customer_metadata
    • Maintaining all existing payment methods and transaction history
  5. Customer now has an enterprise wallet that can be used across all merchants

This upgrade happens automatically during the customer identification process, requiring no additional action from the merchant or customer.

Healthcare Exchange ID Recognition​

Customers initially identified with healthInsuranceExchangeId can have additional identifiers like subscriberId extracted and stored in their wallet.

Exchange ID Recognition Example

Scenario:

  1. Customer is initially identified by healthInsuranceExchangeId
  2. CCG searches EIMP with this identifier
  3. EIMP response contains additional identifiers (subscriberId, groupId, etc.)
  4. CCG extracts these identifiers using enterpriseResponseSearchPath
  5. These additional identifiers are stored in the wallet metadata
  6. On subsequent visits, the customer can be identified by any of these identifiers

Configuration Example:

{
  "value": {
    "sourceCode": "Exchange",
    "healthInsuranceExchangeId": "HIX12345"
  },
  "merchantSearchKey": "$.metadata.healthInsuranceExchangeId",
  "enterpriseSearchKey": "identifiers.payer_memberId",
  "enterpriseValueKey": "healthInsuranceExchangeId",
  "merchantMetadataKey": "healthInsuranceExchangeId",
  "enterpriseResponseSearchPath": "$.[*].identifiers.payer_memberId[*]['healthInsuranceExchangeId', 'subscriberId', 'groupId']",
  "precedence": 2,
  "required": true
}

This configuration extracts not just the healthInsuranceExchangeId but also the associated subscriberId and groupId, enhancing the wallet's identification capabilities.

Multi-Identification Support​

When a customer might be identified through multiple methods (e.g., either payer_memberId or surrogateId), the system can extract all relevant identifiers for future interactions.

Implementation Best Practices​

  • ⚠️ Configure precedence strategically: Set the precedence field in CustomerSearchCriteria based on data volume considerations. Lower precedence (higher priority) should be assigned to criteria that query smaller, more specific datasets to optimize performance. Avoid assigning high priority to criteria that would query hundreds of thousands of records.

  • Balance specificity and coverage: When configuring search criteria, find the optimal balance between highly specific identification (fewer false positives) and sufficient coverage (fewer false negatives).

  • Optimize JSONPath expressions: Keep enterpriseResponseSearchPath expressions as specific as possible to improve performance while ensuring they're robust enough to handle variations in the response structure.

  • Test with representative data: Validate your configuration with a variety of real-world data scenarios, including edge cases like partial matches or missing fields.

Error Handling and Observability​

The wallet upgrade process includes robust error handling:

  • If enterpriseResponseSearchPath doesn't match any data, the system falls back to the next search criteria set
  • If enterprise identity lookup fails, the local wallet remains unchanged
  • Validation errors are logged for debugging and monitoring purposes

Troubleshooting​

When troubleshooting wallet upgrade issues, follow these steps:

  1. Verify that both enterpriseResponseSearchPath and merchantMetadataKey are correctly configured
  2. Check JSONPath syntax for errors using a JSONPath validator
  3. Validate that the response structure matches the expected path using sample responses
  4. Ensure proper precedence configuration for fallback behavior
  5. Verify that wallet metadata is being correctly updated in the database