Customer Creation Process

This document provides a comprehensive overview of the customer creation process in the wallet-customer-service platform. It details the flow, involved entities, event-driven architecture, and best practices for integrating new customers across platform, merchant, and vendor systems.

RELATED DOCUMENTATION

For business logic and API specifications related to customer creation, please refer to the Customer API documentation.

QUICK REFERENCE

The wallet-customer-service manages several related entities for customer data:

• Platform Customer: Central entity storing core customer information (name, email, phone, etc.)
• Enterprise Customer: Links platform customers to enterprise identity systems (e.g., EIMP)
• Merchant Customer: Represents a customer's relationship with a specific merchant
• Merchant Customer Metadata: Key-value pairs of merchant-specific customer data
• Vendor Customer: Represents a customer in a vendor's system (i.e., Stripe)

Customer Creation Flow Diagram

The customer creation process is orchestrated by the service, which coordinates the creation and updating of these entities.

Customer Creation Flow

1. Request Intake & Identifier Resolution

• The system receives a customer creation request containing one or more identifiers:
  • Enterprise ID (from enterprise identity system)
  • HSID (HealthSafe ID)
  • Merchant-specific identifiers (e.g., patientId, subscriberId)
• The system attempts to resolve the customer using these identifiers:
  • Enterprise ID, HSID, and Search criteria lookups are performed in parallel via Identity Service
  • If all parallel lookups return no results, the system performs a direct database lookup by provided identifiers

2. Platform Customer Handling

• If no existing customer is found, a new platform customer is created
• If an existing customer is found, it is updated with any new information
• For each existing platform customer, the system checks if a merchant relationship exists

Platform Customer Creation

Flow

1. When a new customer request comes in, the system checks for existing customers using:

   • Enterprise ID, HSID, and Search criteria lookups are performed in parallel via Identity Service
   • Direct database lookup by provided identifiers (if parallel lookups fail)

2. If no existing customer is found, a new platform customer is created.

3. If an existing customer is found, it is updated with any new information.

Customer Data Sources (Priority Order)

1. Identity Service Golden Record (if available)
2. Request payload data

Enterprise Customer Creation

Enterprise Customer records are only created or updated when a customer is found through the Identity Service using one of the following parallel lookup methods:

• Enterprise ID lookup
• HSID lookup
• Search criteria lookup

When a customer is found only through direct database lookup or is newly created without EIMP identity information, the Enterprise Customer record is not created or updated.

The EnterpriseCustomer entity maintains a link between the wallet platform customer and enterprise identity systems, providing integration with enterprise-level identity services.

Merchant Customer Creation

After platform and enterprise customer records are updated, the merchant customer relationship is created or updated.

Key Steps in Merchant Customer Creation

1. Find existing merchant customer record or create a new one
2. Check if data has changed (to avoid unnecessary updates)
3. Delete existing metadata records
4. Save new merchant customer record
5. Publish event based on whether it's a create or update operation

Platform Customer with New Merchant Association

When a customer is found at the platform level but doesn't have an existing relationship with the requested merchant, the system follows a specific flow:

1. Check for Merchant Association: The system checks if a relationship exists between the platform customer and the specific merchant.

2. Verify Relationship Status: If no merchant-customer relationship is found, the system creates a new association.

3. Create New Merchant Customer Record: The system creates a new MerchantCustomer entity with:

   • Reference to the platform customer ID
   • Reference to the merchant ID
   • Customer data fields (name, email, phone, etc.)
   • Merchant-specific metadata from the request

4. Save Metadata: Any merchant-specific metadata from the request is saved as MerchantCustomerMetadata entries.

5. Publish Event: A MERCHANT_CUSTOMER_CREATED event is published.

6. Vendor Customer Creation: After the merchant-customer relationship is established, the system publishes a WALLET_CUSTOMER_CREATION_INITIALIZED event to trigger the vendor customer creation process.

7. Platform-Level Updates: No changes are made to the enterprise customer relationships or platform customer data, as these already exist.

Distinguishing Between New and Existing Merchant Customers

The system tracks whether a merchant-customer relationship is new to determine whether to publish a MERCHANT_CUSTOMER_CREATED or MERCHANT_CUSTOMER_UPDATED event.

Handling Customer Data Consistency

When adding a new merchant association to an existing platform customer:

1. The system checks if the customer data in the request differs from existing data
2. If customer data is identical, no updates are performed to avoid unnecessary processing
3. If customer data differs, the merchant-customer record is updated with the new information

Vendor Merchant Customer Creation for Existing Platform Customers

When a platform customer exists but doesn't have a vendor merchant customer record for a specific merchant:

1. Platform Vendor Customer Verification: The system checks if a platform-level vendor customer record exists by looking up the customer ID and vendor name.

2. CCG Customer Handling: When a customer is found in CCG (Convenient Checkout Group), the vendor customer creation at the platform level is skipped. The system uses the existing vendor customer record for this customer.

3. Event Processing: When the WALLET_CUSTOMER_CREATION_INITIALIZED event is consumed:

   • For an existing platform customer with no merchant association, the system uses the existing platform vendor customer ID
   • The platform vendor customer ID is used to create a new vendor merchant customer mapping

4. Vendor Merchant Customer Record Creation: A new VendorMerchantCustomer entity is created with:

   • The platform customer ID
   • The merchant ID
   • The vendor's customer ID
   • A status of "CREATED"

5. Payment Method Handling: Any pending payment method setups are processed to ensure payment methods associated with the existing platform customer are properly linked to the new merchant relationship.

6. Notification: After the vendor merchant customer is successfully created, the system publishes a WALLET_CUSTOMER_UPDATED_EVENT to notify other components.

This approach ensures that existing platform customers can be efficiently associated with new merchants without duplicating customer records in vendor systems, maintaining data integrity throughout the ecosystem.

Merchant Customer Metadata Updates

The merchant customer metadata represents custom key-value pairs specific to a merchant-customer relationship:

1. When updating a merchant customer, all existing metadata is first deleted
2. New metadata is created from the request's metadata map and saved with the merchant customer

Vendor Customer Creation

Vendor customers represent the mapping between platform customers and their corresponding entities in vendor systems like Stripe. There are two types of vendor customer relationships:

1. Vendor Platform Customers: A single customer representation in the vendor's platform
2. Vendor Merchant Customers: A customer's relationship with a specific merchant within the vendor's platform

Vendor Platform Customer Creation

Platform vendor customers are created when a VENDOR_PLATFORM_CUSTOMER_CREATED event is consumed.

The process includes:

• Finding existing vendor customer record or creating a new one
• Updating vendor customer with new information
• Saving the vendor customer record

Vendor Merchant Customer Creation

Merchant-specific vendor customers are created when a VENDOR_MERCHANT_CUSTOMER_CREATED event is consumed.

The process includes:

• Creating a new vendor merchant customer record
• Setting the appropriate status
• Saving the record

Vendor Customer Creation Flow

1. Initial Customer Creation:

   • When a customer is initially created, the system publishes a WALLET_CUSTOMER_CREATION_INITIALIZED event
   • This event is consumed by a separate service that creates the customer in the vendor's system

2. Vendor Platform Customer Creation:

   • Once the customer is created in the vendor's platform, a VENDOR_PLATFORM_CUSTOMER_CREATED event is published
   • The service consumes this event and creates a vendor customer record

3. Vendor Merchant Customer Creation:

   • For each merchant the customer is associated with, a VENDOR_MERCHANT_CUSTOMER_CREATED event is published
   • The service consumes these events and creates vendor merchant customer records

Payment Method Integration

Vendor customers play a crucial role in payment method setup:

1. When a payment method setup is initiated but is waiting for customer creation, the system:

   • Finds payment methods waiting for customer creation
   • Updates them with the vendor's customer ID
   • Initiates the payment method setup process

2. The system updates the payment method with the vendor's customer ID, ensuring payment methods are associated with the correct customer in the vendor's system

Event-Driven Architecture

The customer creation process is event-driven, ensuring reliable integration and extensibility:

• WALLET_CUSTOMER_CREATION_INITIALIZED: Published when a platform customer is created
• VENDOR_PLATFORM_CUSTOMER_CREATED: Published when a customer is created in the vendor's platform
• VENDOR_MERCHANT_CUSTOMER_CREATED: Published when a customer is created for a specific merchant in the vendor's system
• WALLET_CUSTOMER_UPDATED_EVENT: Published after vendor customer records are created
• MERCHANT_CUSTOMER_CREATED: Published when a new merchant-customer relationship is established
• MERCHANT_CUSTOMER_UPDATED: Published when an existing merchant-customer relationship is updated

This architecture enables:

• Asynchronous processing and integration with external systems
• Decoupling of customer creation from downstream processes (e.g., payment method setup)
• Easy extension for new vendors or merchant requirements

Database Relationships

The following database relationships are established:

1. Customer Table: The core customer entity

   • Contains basic customer information (name, email, phone, etc.)
   • Referenced by other customer-related tables

2. Enterprise_Customer Table: Links customers to enterprise identity

   • References Customer by customerId
   • Stores enterprise IDs and HSID

3. Merchant_Customer Table: Links customers to merchants

   • References Customer by customerId
   • References Merchant by merchantId
   • Stores merchant-specific customer information

4. Merchant_Customer_Metadata Table: Stores merchant-specific metadata

   • References Merchant_Customer by customerId and merchantId
   • Stores key-value pairs of custom data

5. Vendor_Customer Table: Links platform customers to vendor platform customers

   • Composite primary key of customerId and vendor
   • Stores the vendor's customer ID

6. Vendor_Merchant_Customer Table: Links customers to merchant-specific vendor representations

   • Composite key of customerId, merchantId, and vendor
   • Stores the vendor's merchant-specific customer ID

Best Practices & Recommendations

• Always provide as many identifiers as possible in the customer creation request to maximize matching accuracy.
• Leverage event subscriptions to integrate with downstream systems (e.g., payment, analytics, notifications).
• Ensure idempotency in customer creation logic to avoid duplicate records.
• Regularly audit and reconcile customer data across platform, merchant, and vendor systems.
• Monitor event delivery and processing to ensure all downstream systems are updated as expected.

Trouble Shooting

• Duplicate Customers: Ensure identifier resolution logic is robust and idempotent.
• Missing Vendor Records: Check event delivery and vendor integration logs.
• Stale Metadata: Always delete and recreate merchant customer metadata on update.
• Integration Failures: Use event logs and retry mechanisms for resilience.