KYC Simulator — eKey 2.0 App-to-App KYC to Card Issuance | Pranjal Kumar
VYBE×ISSUER×eKey 2.0
Issuer · Product Development · UAT sandbox (mock)

KYC Simulator

VYBE opens a live account for a Bahrain resident using eKey 2.0 app-to-app authentication through the issuer, then gets a prepaid card issued. Screens follow the eKey 2.0 account-opening journey; every hop between the five systems is logged with its payload.

0 / 0

Sequence trace

click a row to inspect

Payload inspector

Integration blueprint

How VYBE plugs into the issuer’s eKYC and card issuing

VYBE never talks to eKey directly. The issuer owns the eKey client credentials, PKCE verifier, token exchange and government data. VYBE owns the app screens, one forwarding call, the financial survey and the status check.

VYBE builds

  • "Sign up with eKey 2.0" on the landing screen, and the "Authenticate with eKey 2.0" handoff screen, including the "I have eKey 2.0 on another device" path.
  • Register an App Link / Universal Link (e.g. https://app.vybe.com/ekey) as the return URI. Keep vybe://ekey only as fallback.
  • Backend call 1: POST /api/v2/kyc-application. Store applicationId against the VYBE user.
  • Backend call 2: forward code, state, error, error_description to GET /api/v2/ekey/call-back the moment the app receives them.
  • Show the financial survey (source of income, monthly income, US person, trading experience) while background verification runs. It covers FATCA and appropriateness, which eKey does not.
  • Backend call 3: GET /api/v1/kyc-application/{id} with backoff (1s, 2s, 4s, cap 30s) until Verified/Failed.

Issuer provides

  • eKey OIDC session: state, nonce, PKCE S256, bound to the applicationId with the 10-minute consent window shown on the eKey screen.
  • Token exchange, KYC data pull (name, CPR, DOB, nationality, gender, photo), identity pack, Face ID and liveness validation.
  • Customer profile + auto card issuance on VYBE_PREPAID_USD when configured. VYBE gets cardId and masked PAN only.
  • Full PAN/CVV shown through the issuer’s secure card-view SDK, so VYBE stays out of PCI DSS cardholder-data scope.
  • Card loads for P&L withdrawals run through the rules engine LOAD rule (2001) with per-client velocity limits.

Customers who already have an eKey login

  • Log in. VYBE calls POST /api/v2/ekey/auth-session with purpose: LOGIN. eKey is asked for openid only, so the customer sees one confirm screen and Face ID. No data-consent list, no video selfie, no survey.
  • Who is it? The issuer stores the eKey sub against the customer at account opening, then matches it on every log-in. It never calls the KYC data API for a log-in.
  • Still in good standing? On each log-in the issuer checks KYC status, CPR expiry and customer status. An expired CPR still logs in, but triggers a KYC refresh and restricts the card until it is done.
  • Signs up again by mistake. The issuer reads sub from the id_token before pulling KYC data. If it is already linked, it returns Verified with outcome: LINKED_TO_EXISTING and the existing customerId. No second profile, no second card. VYBE signs the customer in.
  • Onboarded by documents before eKey. No sub link exists yet. The issuer falls back to a CPR-hash match after the KYC data pull, then links the sub so every later log-in is the short path.

Data handed to VYBE after Verified

FieldSourceShared with VYBEWhy
fullNameEn / fullNameAreKey KYC APIYesAccount name must match the verified identity
dateOfBirth, nationalityeKey KYC APIYesAge gate and country risk for trading
mobile, mobileVerifiedeKey (General information scope)YesPre-fills VYBE contact details; no SMS OTP needed
cpreKey KYC APIMasked (8•••••12)Minimise national ID spread; the issuer keeps the full value
photoeKey KYC APINoOnly needed for the issuer’s biometric match
cardId, maskedPan, statusIssuer card issuingYesDisplay card; never the full PAN

Fix before VYBE goes live

  • Polling only. Add a signed webhook (kyc.application.updated, HMAC-SHA256) so VYBE isn't hammering the status endpoint at onboarding peaks.
  • Version mismatch. Create and callback are /api/v2, status is /api/v1. Either align or document why.
  • "Failed" isn't actionable. Return a failureReason code (ACCESS_DENIED, AUTH_FAILED, INVALID_STATE, CPR_EXPIRED, NAME_MISMATCH) so VYBE can route the user to retry, support or fallback.
  • eKey only covers CPR holders. VYBE onboards GCC and international clients. The issuer needs a document + liveness fallback behind the same kyc-application API, selected by method.
  • Card issuance gate. Auto-issue on Verified is too early for a CBB investment firm: the survey, appropriateness test, FATCA/CRS and PEP declaration sit with VYBE. Add issueOn: KYC_VERIFIED | CLIENT_APPROVED.
  • Cross-device flow is undocumented. The eKey journey shows "I have eKey 2.0 on another device", but the integration guide only covers web redirect and same-device deep link. Specify the QR/polling contract.
  • Anonymous GET callback. Auth codes land in query strings, so mask them in gateway and app logs and make the issuer’s callback idempotent per state.
  • No log-in endpoint. The guide only defines kyc-application. Without an auth-session (purpose LOGIN) endpoint, every returning customer would go through a full application, consent list and selfie again.
  • Guide copy. Section 7 "Seamless Integration" describes fraud cost reduction. Fix the label before this goes to VYBE.