Skip to main content
Version: v2

Customer Creation

Legend: Class / Handler Method Field / Config Key Event API Endpoint DB Table / Column
Key Points
  • CCG uses three primary identifiers: enterpriseId, hsid, and mcid
  • Identification follows a strict precedence order to ensure consistency
  • Enterprise wallets enable a unified customer experience across merchants
  • Local wallets are created when enterprise identification is not possible but can be shared within merchant groups
  • The findOrCreateCustomer endpoint (POST /customers/find) is the recommended method for customer creation — it performs synchronous identity resolution before returning a response
Who is a Customer?
  • Customers are authenticated users, who have a wallet with the Convenient Checkout system.

Overview​

CCG (Convenient Checkout Gateway) creates and manages customer records using multiple identifiers to ensure accurate mapping and a seamless experience across merchants and channels. The primary identifiers are:

  • hsid (HealthSafe ID)
  • enterpriseId (Enterprise Identity)
  • mcid (Merchant Customer Identifiers)
important

Customer creation requires at least one primary identifier (enterpriseId, hsid, or metadata/mcid); if none is provided, the process cannot continue.

Identifier Requirement

At least one of enterpriseId, hsid, or metadata must be provided. If all three are absent, the API returns an error: "Required any one of the identifier. Enterprise Id or hsid or MCID".

HTTP Status: Always 200 OK on success.

Primary Identifiers

  1. enterpriseId: A global identifier representing a consumer's enterprise identity. This enables CCG to consolidate all wallets and payment methods for a customer across all merchants, providing a unified experience and supporting enterprise wallet upgrades.
    Example: "enterpriseId": "603041336"

  2. hsid: HSID (HealthSafe ID) is the authentication (credentials) method developed by UHG for authenticating users for websites and mobile applications.
    Format: uuid (Universally Unique Identifier)
    Example: "hsid": "123e4567-e89b-12d3-a456-426614174000"

  3. merchant customer identifiers (mcid): Merchant-specific identifiers (such as patientId, subscriberId, dependentCode, exchangeId, etc.) that allow merchants to uniquely identify their customers within their own systems. CCG supports multiple mcids per customer, as defined by each merchant's configuration.
    Example: "patientId": "222333444", "subscriberId": "ABC789"

Types of Wallets

CCG supports two types of wallets to accommodate different customer identification scenarios:

  1. Enterprise Wallet: Created when a customer can be identified with EIMP using enterpriseId or hsid or merchant-specific identifiers (mcid) . This wallet type enables customers to have a unified payment experience across multiple merchants within the enterprise.

  2. Local Wallet: Created when a customer can only be identified using merchant-specific identifiers (mcid) but cannot be matched to an enterprise identity. Local wallets can be shared across merchants that belong to the same merchant group, providing a consistent experience within that group.

Enterprise Wallet Upgradation

Local merchant wallets can be upgraded to enterprise wallets when additional identification is available. For details on how this process works,

Refer Enterprise wallet upgradation and Local to Enterprise Wallet Merge for more details.

Identification Precedence

The system follows a strict precedence order when identifying customers:

  1. enterpriseId - Highest precedence, direct match to enterprise identity
  2. hsid - Second priority, can be resolved to an enterpriseId
  3. mcid - Uses merchant-specific identifiers with configurable matching rules defined in enterpriseSettings

For details on the enterpriseSettings configuration and how it affects customer identification with mcid, see Customer Look up Logic using enterpriseSettings.

Process Flow — findOrCreateCustomer​

Step-by-Step Execution
  1. Validate Request: Calls CustomerRequest.validate() to ensure at least one of enterpriseId, hsid, or metadata is present.
  2. Build Command: Maps the request to a CreateCustomerForMerchantCommand with the merchant ID from the X-Merchant-Id header and vendor set to STRIPE.
  3. Identity Resolution (via CreateCustomerCommandHandler):
    1. Updates metadata with digital-identity-supported IDs.
    2. Performs parallel identity lookups against the Enterprise Identity Management Platform (EIMP):
      • By enterpriseId
      • By hsid
      • By search ID (metadata-based / mcid)
    3. If a golden record is found in EIMP:
      • Searches for an existing customer in CCG matching the golden record's identifiers.
      • If found: updates the customer with identity data (name, email, phone, DOB, ZIP from the identity service, falling back to request values), saves it, handles payment method transfers, and publishes a WALLET_CUSTOMER_CREATION_INITIALIZED event if no vendor-merchant-customer mapping exists yet.
      • If not found: creates a new enterprise wallet from the identity response.
    4. If no golden record and only enterpriseId was provided (no hsid, no metadata): throws an error — "Customer Not found for given Enterprise Id".
    5. If no golden record but hsid or metadata is present: searches for an existing customer by enterpriseId/hsid/merchant-identifier. If found, updates it; if not found, creates a new local wallet from request fields.
    6. Creates or updates the merchant-customer association.
  4. Enrich Response:
    • Fetches the VendorCustomer record (Stripe platform-level) to populate vendorPlatformCustomerId.
    • Fetches the VendorMerchantCustomer record (Stripe merchant-level), if it exists, to populate status, walletVendorMerchantId, and vendorMerchantCustomerId.
    • If no vendor-merchant mapping exists yet, status defaults to INITIATED.
  5. Return 200 OK with the fully resolved CustomerResponse.
Wallet Handling Logic
  • Enterprise Wallet Creation: When a customer's enterpriseId, hsid, or mcid matches a single golden record in EIMP
  • Local Wallet Creation: When a customer cannot be matched in EIMP using mcid, when multiple/ambiguous matches are found, or when EIMP returns no results
  • Wallet Updates: When a customer already exists, the wallet is retrieved and updated with any new information from the identity service (or from the request as a fallback)
  • Payment Method Transfers: When wallets are consolidated, payment methods are transferred to ensure the customer has a unified set of payment methods
  • Special Cases:
    • When a wallet needs to be made inactive, associated payment methods must be handled appropriately
    • When a customer has different identifiers across different merchants, the system may need to consolidate wallets

Customer Identification & Wallet Creation Workflow​

View Identification Workflow Diagram

MCID Identification with Enterprise Settings​

Enterprise Settings Configuration

When identifying customers using merchant customer identifiers (mcid), the system relies on the merchant's enterpriseSettings configuration. This configuration defines:

  1. The specific merchant identifiers used for customer lookup
  2. How these identifiers map to enterprise identity fields
  3. Which fields are required vs. optional for a positive match
  4. The precedence order for trying different identification strategies

For detailed information on how this works, see Customer Look up Logic using enterpriseSettings.

Local Wallet Creation Process​

Local Wallet Creation Workflow

When a customer cannot be identified through EIMP (or when multiple/ambiguous matches are found), a local wallet is created. This process ensures merchants can still provide a consistent payment experience even when enterprise identification isn't possible.

Local wallets created for mcid-only customers are shared across merchants within the same merchant group.

Example Scenarios​

Scenario 1: Customer with enterpriseId — existing wallet
  • Request: Merchant sends POST /customers/find with enterpriseId and X-Merchant-Id header
  • Process:
    1. validate() passes — enterpriseId is present
    2. Identity service finds a golden record for the enterpriseId in EIMP
    3. CCG database finds an existing customer matching the enterpriseId
    4. Customer record is updated with the latest identity data
    5. VendorCustomer and VendorMerchantCustomer records are fetched for response enrichment
  • Result: Returns 200 OK with existing enterprise wallet and status: "CREATED"
Scenario 2: Customer with hsid — new enterprise wallet
  • Request: Merchant sends POST /customers/find with hsid only
  • Process:
    1. validate() passes — hsid is present
    2. Identity service resolves the hsid to a golden record in EIMP
    3. CCG database does not find an existing customer matching the hsid
    4. A new enterprise wallet is created from the identity response
    5. A WALLET_CUSTOMER_CREATION_INITIALIZED event is published
  • Result: Returns 200 OK with new enterprise wallet and status: "INITIATED" (vendor provisioning pending)
Scenario 3: Customer with enterpriseId only — not found in EIMP
  • Request: Merchant sends POST /customers/find with only enterpriseId (no hsid, no metadata)
  • Process:
    1. validate() passes — enterpriseId is present
    2. Identity service finds no golden record for the enterpriseId in EIMP
    3. Since only enterpriseId was provided (no fallback identifiers), the system cannot create a wallet
  • Result: Returns error — "Customer Not found for given Enterprise Id"
Scenario 4: MCID with single match in EIMP
  • Request: Merchant sends POST /customers/find with metadata (e.g., patientId)
  • Process:
    1. validate() passes — metadata is present
    2. Identity service searches by mcid using the merchant's enterpriseSettings criteria
    3. A single matching golden record is found in EIMP
    4. CCG database checks if a customer exists for this identity
    5. If not found, a new enterprise wallet is created
  • Result: Returns 200 OK with enterprise wallet
Scenario 5: MCID with multiple matches or no match in EIMP
  • Request: Merchant sends POST /customers/find with metadata (e.g., patientId)
  • Process:
    1. validate() passes — metadata is present
    2. Identity service searches by mcid but finds multiple matching records (or no records)
    3. System cannot determine a single enterprise identity
    4. A local wallet is created using the mcid
  • Result: Returns 200 OK with local wallet shared within the merchant group
Scenario 6: No identifiers provided
  • Request: Merchant sends POST /customers/find with no enterpriseId, hsid, or metadata
  • Process:
    1. validate() fails — none of the required identifiers are present
  • Result: Returns error — "Required any one of the identifier. Enterprise Id or hsid or MCID"

Integration with Merchant Groups​

The merchant groups concept is critical for local wallet functionality:

  • Merchants within the same group can share local wallets
  • A customer identified by mcid at one merchant can have their wallet reused at another merchant in the same group
  • This enables scenarios like healthcare provider networks or related retail chains to provide a consistent customer experience