Registration & KYC Lock Mechanism

A lock holds a freshly activated card back from use until a verification event releases it: axis-service activates the card, then immediately suspends it at Tribe (status T) and flags it kyc_locked. Two program-configuration flags can trigger it — registration_required and kyc_required — but today they feed a single predicate and produce a physically identical hold; there is no separate "registration lock" state.

Fund timing is folded into the same decision: a locked card defers its initial load, parking the amount in a KycLockEntity row to be applied at release. The only thing that releases it is a verifyIndividual call.

KycLockService.isRegistrationLockRequired() / KycLockService.isKycRequired() / ProgramConfigurationRepository.getByDesignId().

The predicate — registration OR kyc

Every lock-related branch in the service asks one method. It loads the card's ProgramConfigurationEntity by designId and returns true if either flag is set. There is no third "lock" flag and no notion of which trigger fired — the result is one boolean.

 // KycLockService.isRegistrationLockRequired(card) boolean requiresKyc = cfg.isKycRequired(); boolean requiresRegistration = cfg.isRegistrationRequired(); return requiresRegistration || requiresKyc; // config missing for designId -> false (no lock)

A separate isKycRequired() returns the kyc flag alone. It does not gate any lock — it only feeds the DTO field requiresKyc (see the D4 lie in section 6).

Truth table

What actually exists — live data, prod vs staging

CardActionHandler.activateCard() (single, inline) / GroupCardActionHandler.activateCard() (group, deferred) — identical lock logic.

Activate first, then hold

Activation always runs to completion on Tribe before the lock is considered. The card is genuinely activated, its Activated status recorded — and only then, if the predicate says so, is it pulled back to Suspended.

1. Already locked? Bail. If pce.isKycLocked() is already true, throw IllicitModificationException(alreadyActivated). A locked card can't be re-activated.
2. Activate on Tribe.activateCard(spiCardId, ref) — the card goes live (status A). addStatusUpdate(Activated) records it.
3. If isRegistrationLockRequired → suspend & flag. Set pce.setKycLocked(true), call Tribe changeCardStatus(spiCardId, "T", 3) to Suspended, and record a second status update of Suspended. The card is now activated-then-held. No KycLockEntity is created here — that only happens on a funding path.

Card status the handler writes

CardActionHandler.loadFunds() / isKycRequiredAndNotYetVerified() / persistKycLock() / checkFundingBalance().

A locked load defers instead of loading

For load and activateWithLoad, the handler asks the lock predicate again — this time to decide whether to load now or park the load for later. If the card is locked and has no existing lock row, the amount, channel and reference are serialized into a KycLockEntity and the method returns without touching Tribe.

 // loadFunds(amount, channel) if (isKycRequiredAndNotYetVerified(card)) { persistKycLock(cardId, spiCardId, ref, amount, channel); // park it return; // no Tribe load now } executeLoadAndRecordTransfer(...); // load now // isKycRequiredAndNotYetVerified = // no existing KycLockEntity // AND isRegistrationLockRequired(card)

1. Balance check — skipped when locked.checkFundingBalance() early-returns the moment isRegistrationLockRequired is true. A locked load is never checked for sufficient funds up front (D3).
2. Park the load in a KycLockEntity.persistKycLock() writes one row keyed by cardId: currencyAmount + loadChannel (both JSON), referenceNumber, description="card load", createdAt.
3. Open program → load immediately. No lock → executeLoadAndRecordTransfer moves funds and loads the card on Tribe in-thread.

POST /api/cpm/v1/partners/{partnerExtId}/kyc/inquiries/verifyIndividual → KycInquiryHandler.onVerifyIndividual → activateAndLoadCard.

Release = un-suspend at Tribe, then replay the parked load

There is exactly one code path that clears a lock. A KYC verification result posts to verifyIndividual; the handler looks the card up and runs activateAndLoadCard. It is guarded by two preconditions:

1. Precondition — card must be Tribe "T".isCardNotSuspended() reads the live Tribe status. If it is not "T", the handler logs a warning and returns early. A card that was never suspended is silently a no-op (D2).
2. Activate on Tribe.changeCardStatus(spiCardId, "A", 3) brings the card back to Activated, and setKycLocked(false) clears the flag.
3. Precondition — a KycLockEntity must exist.getKycLockEntity(cardId) calls KycLockEntity.findFirstByExternalRef; if it returns null it throws KycLockException. No row, no load, hard failure (D1).
4. Fund transfer, then load. If isAlreadyInitiallyFunded(cardId) is false: run the A→B processFundTransfer, then loadCard with the stored currencyAmount + loadChannel from the lock row.

How each entry path lands at the release gate

The release path needs the card to be both suspended ("T") and backed by a KycLockEntity. Only one of three entry combinations satisfies both.

Every place the lock predicate is consulted

Where the lock state is persisted

The as-built defects, worst first. These are current reality, not proposals — they motivate the redesign, they don't prejudge it.