Skip to main content
Version: v2

Enterprise Wallet Upgradation

Legend: Class / Handler Method Field / Config Key Event API Endpoint DB Table / Column
Quick Reference
  • Purpose: Upgrade local merchant wallets to enterprise wallets with enhanced identification
  • Key Mechanism: Uses enterpriseResponseSearchPath (JSONPath) to extract additional identifiers from the EIMP golden record response
  • Implementation: AbstractCustomerHandler.findCustomerByEnterpriseIdOrHsidOrMerchantIdentifier(goldenRecord, command) with getConfiguredEnterpriseResponseSearchPaths()
  • Process Flow: Golden record found → Extract values via enterpriseResponseSearchPath → Build enriched metadata → Search CCG DB for local wallet match → Upgrade to enterprise wallet
  • Configuration: Set enterpriseResponseSearchPath and merchantMetadataKey in CustomerSearchCriteria for criteria that should enrich wallet metadata
  • 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 through the EIMP golden record, without requiring any customer action.

The upgrade process is triggered during the findOrCreateCustomer flow (POST /customers/find) when a golden record is successfully retrieved from EIMP. The core implementation lives in AbstractCustomerHandler.

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 POST /customers/find, 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 and finding a golden record in EIMP
  2. Extracting additional identifiers from the EIMP golden record response using enterpriseResponseSearchPath (JSONPath)
  3. Enriching the metadata used for CCG database lookup with the extracted values (keyed by merchantMetadataKey)
  4. Using the enriched metadata to find an existing local wallet in CCG that can be upgraded

The upgrade happens without any disruption to the customer experience, preserving all payment methods and transaction history. After upgrade, the Local to Enterprise Wallet Merge process handles payment method consolidation.

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 and a golden record is returned from EIMP
  2. System calls getConfiguredEnterpriseResponseSearchPaths() which:
    • Loads Merchant.orderedCustomerSearchCriteria from the database
    • Sorts OrderedCustomerSearchCriteria sets by ascending precedence
    • Sorts CustomerSearchCriteria within each set by ascending precedence
    • Filters to only criteria that have both merchantMetadataKey and enterpriseResponseSearchPath non-blank
  3. For each matching criterion, values are extracted from the golden record response using JsonUtil.getJsonPathObject(goldenRecord, String[].class, enterpriseResponseSearchPath)
  4. An enriched metadata map is built: merchantMetadataKey → first extracted value. This map is then merged with the original request metadata (using putAll)
  5. The enriched metadata is used to search for an existing customer in CCG via customerQueryHandler.findCustomerByIdentities() — this query can match a local wallet that was created with different identifiers but is now linkable through the enriched data
  6. If no customer is found with enriched metadata, a fallback search is performed using only the original request metadata
  7. If a local wallet is found in CCG, it gets upgraded to an enterprise wallet through the CreateCustomerCommandHandler flow, which also triggers the merge process to transfer payment methods
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 in the CCG database
    • Since the previous visit, this MCID has been associated with an enterprise record in EIMP
    • No enterpriseResponseSearchPath processing needed — the direct MCID match via findCustomerByEnterpriseIdOrHsidOrMerchantIdentifier(command) (without golden record) is sufficient
    • Example: Customer returns to merchant with same patientID, which now has a matching enterprise record

  2. Advanced Upgrade Path (UpgradeLocalWallet):

    • Triggered when getConfiguredEnterpriseResponseSearchPaths() finds criteria with both enterpriseResponseSearchPath and merchantMetadataKey configured
    • Extracts additional identifiers from the EIMP golden record using JSONPath expressions
    • Builds an enriched metadata map that combines the extracted values with the original request metadata
    • The enriched metadata enables matching a local wallet that was created with different identifiers than what's in the current request
    • Example: Customer identified via subscriberId but matched to a local wallet created with dependentCode — because enterpriseResponseSearchPath extracted the dependentCode from the EIMP 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.

Merge / Upgrade Summary​

When and How a Merge or Upgrade Is Triggered

The scenarios below explain how merge/upgrade behavior works depending on merchant configuration, merchant group boundaries, and enterprise identity resolution.

Same Merchant (M1) — Different Precedence Criteria​

M1 can have multiple sets of search criteria, each with a precedence order (e.g., subscriberId + dependentCode at P1, exchangeId at P2). When a request comes through M1, the highest matching precedence group is used to find the local wallet. Merge or upgrade happens using whichever criteria matched first.

Same Merchant Group (M1 + M2 in Same Group)​

M1 has a local wallet, M2 has an enterprise wallet, and both are in the same merchant group. A request through M1 searches across all merchants in the group, finds M2's enterprise wallet, and triggers a merge or upgrade.

This is the intended cross-merchant path — bounded to the group to keep the search performant.

Different Merchant Groups (M1 + M2 in Different Groups)​

M1 can still trigger a merge/upgrade against M2's enterprise wallet even when they are in different groups:

  1. M1's request goes to IMDM
  2. IMDM returns a golden record with an enterpriseId
  3. The enterprise customer lookup by enterpriseId has no group boundary — it searches globally across all groups
  4. Finds M2's enterprise wallet → merge or upgrade happens
note

The group boundary only applies to the local wallet search (metadata-based). Once an enterprise identity is resolved via IMDM, the enterprise customer table is searched globally.

Why M2 (Enterprise Merchant) Never Triggers Merge/Upgrade​

M2's wallet is already enterprise — there is no local wallet to find. Re-running M2's enterprise settings validation against an already-linked wallet adds unnecessary overhead with no benefit.

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, implemented in AbstractCustomerHandler:

  • If enterpriseResponseSearchPath doesn't match any data in the golden record (returns null or empty array), the extracted value is filtered out and the criterion is skipped
  • If no criteria have both enterpriseResponseSearchPath and merchantMetadataKey configured, the enriched metadata map will be empty and the system falls back to searching with original metadata only
  • If enterprise identity lookup fails entirely, the local wallet remains unchanged and the findOrCreateCustomer flow continues with local wallet creation
  • Duplicate merchantMetadataKey values across criteria are resolved with (actual, overridden) -> overridden — later criteria override earlier ones
  • All identity lookups and wallet operations 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