Skip to main content
Version: v2

Local to Enterprise Wallet Merge

Quick Reference
  • Wallet Merge: Merges local wallets to existing enterprise wallets
  • Payment Handling: De-duplicates and transfers payment methods
  • Benefits: Preserves payment history, creates seamless cross-merchant experience

Overview​

The Local to Enterprise Wallet Merge functionality provides a critical upgrade path within the Common Checkout Gateway (CCG) platform. This process enables the seamless transition from isolated local wallets to unified enterprise-level wallets, ensuring customers maintain access to their payment methods while gaining the benefits of enterprise-wide identity.

Key advantages of this functionality include:

  • Identity Unification: Combining fragmented customer identities
  • Payment Method Consolidation: Preserving and consolidating payment methods
  • Cross-Merchant Experience: Enabling wallet use across multiple merchants
  • Data Continuity: Maintaining transaction history and preferences
Architecture Diagram
Merge Process

A wallet merge happens when a local wallet needs upgrading to an enterprise wallet, facilitating unified identity.

Process Flow​

  1. Detect Merge Trigger
    • System identifies a merge opportunity based on new or enriched customer identifiers (e.g., patient ID, insurance ID, or enterprise system match).
    • Decision: Is there a matching active enterprise wallet and active local wallet?
  2. Check for Existing or Failed Migration
    • Look up migration records for the local customer.
    • If a migration is already in progress or failed, resume or retry as appropriate.
  3. Create Migration Record
    • If no migration exists, create a new migration record with status IN_PROGRESS.
    • Log the initiation for audit and monitoring.
  4. Deactivate Local Customer
    • Mark the local customer as inactive to prevent further wallet use.
    • Retain the record for audit/history.
  5. Identify and Transfer Payment Methods
    • Gather all payment methods from the local wallet.
    • For each method, check if it already exists in the enterprise wallet (using fingerprint or unique identifier).
    • Special handling for payment method types:
      • Cards: Transfer all valid cards.
      • ACH/Bank Accounts: Only transfer ACTIVE accounts; delete invalidated ones.
  6. De-duplicate and Update Payment Methods
    • If a duplicate payment method exists in both local and enterprise wallets:
      • Compare the last updated timestamps of each payment method.
      • If the local wallet's payment method is more recent, update the enterprise wallet with the local method's details.
      • If the enterprise wallet's payment method is more recent or equal, retain the enterprise version and do not update.
      • Always ensure only one active version of each payment method remains in the enterprise wallet after deduplication.
    • Update enterprise wallet with latest payment method info.
  7. Publish Events
    • For each migrated or replaced payment method, publish a PAYMENT_METHOD_REPLACED event to notify merchants with local wallet and PAYMENT_METHOD_ADDED event to notify merchant with enterprise wallet.
    • For each duplicate payment method, publish a PAYMENT_METHOD_REPLACED event to notify merchants with local wallet and PAYMENT_METHOD_UPDATED event to notify merchant with enterprise wallet.
  8. Finalize Migration
    • Update migration record status to COMPLETED.
    • Log completion and notify monitoring systems.
  9. Error Handling & Recovery
  • If any step fails, update migration status to FAILED and log error details.
  • Allow for retry/resume of failed migrations without data loss.
caution

When payment methods are deleted as part of merge process, PAYMENT_METHOD_DELETED event should not be sent to merchant

Migration States​

  • IN_PROGRESS: Migration started but not COMPLETED
  • COMPLETED: All payment methods successfully transferred
  • FAILED: Error occurred during migration (can be retried)
Testing

  • Basic Merge:

    • Local wallet with unique payment methods is merged into an enterprise wallet.
    • Verify all payment methods and history are preserved.

  • Duplicate Payment Methods:

    • Both local and enterprise wallets have the same card or bank account.
    • Ensure deduplication logic retains only the most recent/valid method.

  • Mixed Payment Types:

    • Local wallet has cards, enterprise wallet has ACH/bank accounts (and vice versa).
    • Confirm all valid payment methods are transferred and properly categorized.

  • Failed Migration and Retry:

    • Simulate a migration failure (e.g., network error, data conflict).
    • Ensure migration can be retried and completes successfully without data loss.

  • Inactive Local Customer:

    • After merge, local customer should be marked inactive and not usable for new transactions.

  • Event Publishing:

    • Confirm that all relevant events (e.g., PAYMENT_METHOD_REPLACED) are published and received by downstream systems.

  • Edge Cases:

    • Local wallet with no payment methods.
    • Enterprise wallet already contains all local payment methods.
    • Large number of payment methods (stress test).

  • Audit and History:

    • Verify that transaction and payment history is preserved and accessible post-merge.

  • Orphan/Residual Data:

    • Ensure no orphaned or duplicate payment methods or customer records remain after merge.