Checking access…

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.
Integration Details
  • Endpoint: POST /v2/customers/find
  • Scope: Internal CCG endpoint — triggered as part of session and payment flows, not called directly by external merchants.
  • API Version: v2
  • Prerequisites: Valid X-Merchant-Id header. At least one of enterpriseId, hsid, or metadata (mcid) must be provided.
  • Internal API Reference: /engineering-guide/internal-api-v2/

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,

🔒 InternalInternal information — not visible in the public (merchant) site.
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
🔒 InternalInternal information — not visible in the public (merchant) site.

Vendor Customer Creation Model​

How CCG creates and returns vendor customer data (e.g., Stripe or Optum Bank customer records) depends on the CustomerModel configured per vendor for the merchant.

CustomerModelVendor customer created?vendorContext response
TWO_TIERYes — CCG creates a customer record in the vendor's platformIncludes real vendorPlatformCustomerId and vendorMerchantCustomerId from the vendor's API
PASS_THROUGHNo — vendor manages its own customer lifecyclevendorPlatformId is null; vendorPlatformCustomerId is set to the customer's HSID
ONE_TIERReserved — not currently used—

The vendorContext field in the response is a map keyed by vendor name (e.g., STRIPE, OPTUM_BANK). Callers can request context for specific vendors by passing the X-Vendors header:

X-Vendors: STRIPE,OPTUM_BANK

When X-Vendors is omitted, all vendors configured for the merchant are included.

For the full engineering details and configuration reference, see Vendor Customer Model Configuration.

API Request​

API Specification

POST /v2/customers/find is an internal CCG endpoint. It is invoked by CCG as part of session and payment flows. For the full request schema and field definitions, see the Internal API Reference.

Request with enterpriseId
POST /v2/customers/find
X-Merchant-Id: <merchant-id>

{
  "enterpriseId": "603041336"
}
Request with hsid
POST /v2/customers/find
X-Merchant-Id: <merchant-id>

{
  "hsid": "123e4567-e89b-12d3-a456-426614174000"
}
Request with merchant identifiers (metadata)
POST /v2/customers/find
X-Merchant-Id: <merchant-id>

{
  "metadata": {
    "patientId": "222333444"
  }
}

API Response​

POST /v2/customers/find always returns 200 OK on success. The operation is idempotent — it creates or updates the customer record and returns the resolved state.

Success — existing enterprise wallet (status: CREATED)
{
  "walletCustomerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "CREATED",
  "enterpriseId": "603041336",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com"
}
Success — new customer, vendor provisioning pending (status: INITIATED)
{
  "walletCustomerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "INITIATED",
  "enterpriseId": "603041336"
}
Error — no identifier provided
{
  "error": "Required any one of the identifier. Enterprise Id or hsid or MCID"
}
Error — enterpriseId not found in EIMP (no fallback identifier)
{
  "error": "Customer Not found for given Enterprise Id"
}

Status Handling​

The status field in the customer response reflects vendor provisioning state:

StatusMeaning
INITIATEDCustomer record created in CCG; vendor provisioning (e.g., Stripe customer registration) is pending asynchronously.
CREATEDVendor provisioning complete — customer is ready for payment method setup and payments.
info

The endpoint always returns 200 OK. Subscribe to the WALLET_CUSTOMER_CREATION_INITIALIZED event to be notified when vendor provisioning completes and status transitions from INITIATED to CREATED.

Error Handling​

ScenarioBehaviour
None of enterpriseId, hsid, metadata providedValidation error — "Required any one of the identifier. Enterprise Id or hsid or MCID"
enterpriseId provided but not found in EIMP and no fallback identifiersNot-found error — "Customer Not found for given Enterprise Id"
Invalid or missing X-Merchant-Id headerMerchant lookup error — request rejected before customer resolution

For session-level and payment-level error codes that can occur when customer creation is triggered as part of those flows, see Session Error Codes and Payment Error Codes.

FAQ​

Q: Does calling this endpoint multiple times for the same customer create duplicates?

  • No. The endpoint is idempotent. If a customer record already exists matching the provided identifiers, it is retrieved and updated — not duplicated.

Q: What happens if both enterpriseId and hsid are provided?

  • enterpriseId takes precedence. If a golden record is found by enterpriseId, the hsid is used only as a supplementary signal.

Q: Why does the customer return status: INITIATED instead of CREATED?

  • INITIATED means the CCG record exists but the vendor (e.g., Stripe) customer has not been provisioned yet. The provisioning happens asynchronously. Wait for the WALLET_CUSTOMER_CREATION_INITIALIZED event before attempting payment method setup.

Q: Can a local wallet be promoted to an enterprise wallet later?

  • Yes. If enterprise identity becomes available (e.g., user logs in with their HSID), a subsequent call to this endpoint with the hsid can upgrade the local wallet. See Wallet Upgrade Logic for details.

Integration Checklist​

  • X-Merchant-Id header is configured correctly for each environment
  • At least one of enterpriseId, hsid, or metadata is included in every request
  • Response status is checked — handle INITIATED (provisioning pending) separately from CREATED (ready)
  • Event listener is configured for WALLET_CUSTOMER_CREATION_INITIALIZED to detect when vendor provisioning completes
  • Error handling is implemented for missing-identifier and not-found-in-EIMP cases
  • Retry logic does not duplicate customers — confirm idempotency is relied on correctly
  • Tested in staging with all three identifier types (enterpriseId, hsid, metadata)