EIMP

Overview

EIMP (Enterprise Identity Management Platform) is an internal service leveraged by CCG to retrieve, validate, and manage enterprise customer identities. It acts as the authoritative source for enterprise customer records, ensuring that each customer is uniquely identified and consistently referenced across systems.

Role in CCG Workflows

• When a merchant initiates a session, CCG calls EIMP to obtain enterprise customer details.
• EIMP helps match the incoming customer data to an existing Enterprise ID (EID) or return no results found.
• This process is transparent to merchants; all EIMP interactions are managed by CCG.

Customer Creation & Update Flow

1. Merchant sends customer information to CCG.
2. CCG calls EIMP to retrieve or validate the enterprise customer record.
3. If EIMP record is found:
   • If the customer exists in CCG, their information is updated.
   • If not, a new customer and enterprise wallet are created in CCG.
4. If EIMP record is not found:
   • A local customer is created in CCG, and a local wallet is returned.

Key Considerations

• The Customer table in CCG enforces a unique index on enterprise ID to prevent duplicate enterprise customers.
• If a customer with the same EID exists but is inactive, an exception will occur during creation or update.
• Merchants do not interact with EIMP directly; all integration is handled by CCG.

Error Handling

• If EIMP is unavailable or returns errors, CCG will fall back to creating a local customer record.
• Proper error handling and validation are essential to maintain data integrity.

APIs

EIMP provides two main APIs for accessing enterprise customer information:

1. Read API

• Use the Read API to fetch customer information by unique identifiers such as hsid or enterpriseId.
• This is ideal when you already have a specific ID and need to retrieve the corresponding customer record.

2. Search API

• Use the Search API to find customers using multiple filters, such as date of birth (dob), name, or other identifiers.
• This is useful for scenarios where you need to locate a customer but only have partial information or need to search across several fields.

---

EIMP Event Processing

CCG processes EIMP events to keep wallet customer records synchronized with upstream identity changes.

Event Pipeline

1. The wallet-migration-service consumes raw EIMP MasterIndividual events from Kafka.
2. The migration service determines the event type (SPLIT, SPLIT_AND_MERGE, MERGE, or DELETE) by analyzing old and new record change types in the event payload.
3. The migration service determines the eimpDeleted flag — set to true when the master individual is no longer active AND no current records exist.
4. The migration service publishes a normalized EimpMasterIndividual event (including affected enterprise IDs) to Event Grid.
5. The wallet-customer-service (EimpEntityChangeConsumer) consumes the event and dispatches it to EimpEventProcessor based on event type.

Event Types

Event Type	Description
SPLIT	An enterprise identity was split — one or more records were split from old records, and no new records were merged in
SPLIT_AND_MERGE	An enterprise identity was split and merged — records were both split from old records and merged into new records
MERGE	Multiple enterprise identities were merged — one or more records were merged into existing records
DELETE	Records were deleted from the enterprise identity — old records have DELETE change type, and no new records exist

Key Flag: eimpDeleted

Each event carries an eimpDeleted boolean flag, determined by the migration service. It is set to true when the master individual is not active AND its entity change contains no current records (null or empty). When true, it triggers customer inactivation in the customer service regardless of event type.

Summary of Actions per Event

Event Type	eimpDeleted	Inactivate	Override EID	Clear HSID	Purge Payment Methods	Purge Merchant IDs	Refresh Demographics
SPLIT / SPLIT_AND_MERGE	false	❌	❌	Via Identity*	✅	✅	✅
SPLIT / SPLIT_AND_MERGE	true	✅	✅	✅ Unconditional	✅	✅	❌
MERGE	false	❌	❌	Via Identity*	❌	✅	✅
MERGE	true	✅	✅	✅ Unconditional	❌	✅	❌
DELETE	false	❌	❌	Conditional**	❌	❌	❌
DELETE	true	✅	✅	✅ Unconditional	✅	✅	❌

* Via Identity: HSID is set based on Identity Service response — exactly 1 valid HSID → set; 0 or multiple → clear to null.
** Conditional: Only cleared if the current HSID matches an old HS_ID record from the event payload.

---

SPLIT / SPLIT_AND_MERGE Events

When eimpDeleted = false

The enterprise identity was split or split-and-merged but still exists.

1. Look up the Enterprise Customer by enterpriseId. If not found, log and complete (no-op).
2. Create an EIMP tracking record with status PROCESSING.
3. Delete all payment methods for the customer. Retry verification up to 3 times.
4. Delete all merchant customer identifiers for the customer.
5. Refresh demographics from the Identity Service. Update both Customer and EnterpriseCustomer.
6. Update HSID based on Identity Service response.
7. Mark tracking record COMPLETED.

When eimpDeleted = true

The enterprise identity was split/split-and-merged AND deleted from EIMP.

1. Inactivate Customer — set Customer.inactive = true.
2. Override enterprise identifiers — append inactivation suffix to enterprise ID on both Customer and EnterpriseCustomer.
3. Clear HSID — set EnterpriseCustomer.hsid = null unconditionally.
4. Create an EIMP tracking record with status PROCESSING.
5. Delete all payment methods for the customer.
6. Delete all merchant customer identifiers.
7. No demographics refresh — the customer is being inactivated.
8. Mark tracking record COMPLETED.

---

MERGE Events

When eimpDeleted = false

Enterprise identities were merged but still exist.

1. Look up the Enterprise Customer by enterpriseId. If not found, log and complete (no-op).
2. Create an EIMP tracking record with status PROCESSING.
3. Delete all merchant customer identifiers (payment methods are NOT deleted).
4. Refresh demographics from the Identity Service.
5. Update HSID based on Identity Service response.
6. Mark tracking record COMPLETED.

When eimpDeleted = true

Enterprise identities were merged AND the old identity was deleted from EIMP.

1. Inactivate Customer — set Customer.inactive = true.
2. Override enterprise identifiers — append inactivation suffix.
3. Clear HSID — set EnterpriseCustomer.hsid = null unconditionally.
4. Create an EIMP tracking record with status PROCESSING.
5. Delete all merchant customer identifiers.
6. No payment method deletion for MERGE events.
7. No demographics refresh — the customer is being inactivated.
8. Mark tracking record COMPLETED.

---

DELETE Events

When eimpDeleted = false

A record was removed from the enterprise identity but the identity itself still exists.

1. Conditional HSID clearing — extract HS_ID source records from the event's eimpOldRecords. If the current EnterpriseCustomer.hsid matches one of the old HS_IDs, clear it to null. Otherwise, leave it unchanged.
2. Validate Customer ID match — look up both EnterpriseCustomer and Customer by enterpriseId. Verify their customerId values match. If mismatch, save FAILED status and throw an error.
3. Create an EIMP tracking record with status PROCESSING.
4. No payment method deletion.
5. No merchant identifier deletion.
6. No demographics refresh.
7. Mark tracking record COMPLETED.

When eimpDeleted = true

The enterprise identity was deleted from EIMP entirely.

1. Skip conditional HSID clearing — handleEimpDeleted will unconditionally clear HSID.
2. Validate Customer ID match — mismatch results in FAILED status.
3. Inactivate Customer — set Customer.inactive = true.
4. Override enterprise identifiers — append inactivation suffix.
5. Clear HSID — set EnterpriseCustomer.hsid = null unconditionally.
6. Create an EIMP tracking record with status PROCESSING.
7. Delete all payment methods.
8. Delete all merchant customer identifiers.
9. No demographics refresh.
10. Mark tracking record COMPLETED.

---

HSID Handling

Demographics Update Path (SPLIT, SPLIT_AND_MERGE, MERGE — eimpDeleted = false)

When refreshing demographics from the Identity Service, HSID is always updated:

Identity Service Response	Action
Exactly 1 valid HSID (valid UUID format)	Set EnterpriseCustomer.hsid to that value
0 valid HSIDs (empty list, all invalid format, null entries)	Set EnterpriseCustomer.hsid = null
Multiple valid HSIDs (2+)	Set EnterpriseCustomer.hsid = null (ambiguous)
Identifiers or HSID identifiers are null	Set EnterpriseCustomer.hsid = null
Exception during HSID processing	Log warning, leave HSID unchanged

DELETE Event Conditional HSID Clearing (eimpDeleted = false)

For DELETE events where eimpDeleted = false, HSID clearing is conditional:

1. Extract eimpOldRecords from the event.
2. Filter records where sourceSystem = "HS_ID" and sourceRecordId is a valid UUID.
3. If the current EnterpriseCustomer.hsid matches any of these old HS_IDs → clear to null.
4. If no match → leave HSID unchanged.

No clearing occurs when:

• eimpOldRecords is null or empty
• No records with sourceSystem = "HS_ID"
• sourceRecordId is null or not a valid UUID
• Current HSID is null or doesn't match any old HS_IDs

Inactivation Path (eimpDeleted = true — any event type)

HSID is always unconditionally cleared to null as part of the inactivation flow.

---

Demographics Update Strategy

Enterprise Customer (authoritative source: Identity Service)

The Enterprise Customer record always follows the Identity Service response. All fields are overwritten, including setting to null when a value is not provided.

Field	Source	Null Behavior
firstName	user.getGivenName()	Set to null if not provided
lastName	user.getFamilyName()	Set to null if not provided
email	Primary Email → any first email	Set to null if not provided
dateOfBirth	user.getBirthDate() (formatted yyyy-MM-dd)	Set to null if not provided
phone	Mobile Telephone → Home Telephone → Unknown Telephone → any first	Set to null if not provided. Preserves existing countryCode (defaults to "1")
zip5	Recently updated: Primary Residence → Mailing Residence → Unknown Residence. Fallback: Primary Residence → Mailing Residence → Unknown Residence → any first. Trimmed to 5 chars.	Set to null if not provided
hsid	See HSID Handling section	See HSID Handling section

Customer (base customer record)

The Customer record uses additive updates — fields are only overwritten when the Identity Service provides a non-null, non-empty value.

Field	Null Behavior
name	Always set (concatenation of first + last name)
firstName / lastName	Always set from identity
email	Only set if non-empty from identity
dateOfBirth	Only set if non-empty from identity
phone	Only set if non-empty from identity. Preserves existing countryCode (defaults to "1")
zip5	Only set if non-empty from identity. Trimmed to 5 chars.

When Demographics Update is Skipped

Demographics are NOT refreshed in the following scenarios:

• eimpDeleted = true (any event type) — customer is being inactivated
• DELETE event with eimpDeleted = false — no demographics update performed
• Enterprise ID not found in Identity Service — logs error, completes gracefully
• Customer not active — Enterprise Customer still updated, but Customer update skipped
• Enterprise Customer not found — Customer still updated, but Enterprise Customer update skipped

---

EIMP Event Error Handling

Scenario	Behavior
Enterprise Customer not found by enterprise ID (SPLIT/MERGE)	Log info, complete gracefully (no-op)
Customer ID mismatch in DELETE	Save FAILED status, throw error
Customer or Enterprise Customer not found in DELETE	Throw error
Payment method deletion fails	Set status to FAILED, save, complete gracefully
Merchant customer handler fails	Set status to FAILED, save, complete gracefully
Payment method verification exhausts retries	Log error, continue to delete merchant customer identifiers
HSID clearing DB error (DELETE conditional path)	Log warning, swallow error, continue processing
HSID processing exception (demographics path)	Log warning, leave HSID unchanged
Identity Service returns empty	Log error, skip demographics update, continue

---

See Also

• Enterprise Wallet Overview
• Enterprise Settings