Immersve Docs
Github X

Detecting KYC Completion

After a cardholder initiates the KYC process, you need to detect when the KYC evaluation is complete. Immersve provides two integration approaches:

  • Backend Integration (Recommended): Use webhooks with minimal calls to spending prerequisites.

  • Direct Integration: Poll spending prerequisites while the user is actively waiting.

Unacceptable Usage: Continuously polling the spending prerequisites endpoint at high frequencies or for extended periods is not supported and may result in rate limiting. The guidance below explains acceptable integration patterns.

Backend Integration

This approach is recommended for partners with backend infrastructure that can receive and process webhooks. It minimizes API calls and provides real-time updates.

  1. Configure Webhook Endpoint – Set up your webhook endpoint to receive KYC status updates. See Configuring Webhook Listeners for webhook configuration and KYC webhook topics.

  2. Initiate KYC Process – Follow the appropriate guide to initiate KYC: Partner Conducted KYC or Immersve Conducted KYC.

  3. Wait for Webhook – Once you receive the kyc-succeeded webhook, the cardholder can proceed to activate their card.

  4. Webhook Failure Recovery – Immersve retries webhooks for approximately 24 hours. If your system is down for an extended period and misses all retry attempts, you can check affected cardholders' KYC status by calling Get Spending Prerequisites.

Direct Integration

This approach is suitable for partners without backend infrastructure or those who want a simpler implementation. It relies on polling spending prerequisites while the user is actively engaged in the card onboarding flow.

  1. Initiate KYC Process – Follow the appropriate guide to initiate KYC: Partner Conducted KYC or Immersve Conducted KYC.

  2. Short-Duration Polling – While the user is actively waiting on a card activation pending screen in your application, poll Get Spending Prerequisites at a reasonable interval (e.g., every 5-10 seconds). Continue polling only while the user remains on the pending screen. Stop polling if the user navigates away or after a short timeout (e.g., 2-3 minutes).

  3. Detect Completion – When the KYC stage shows "status": "ok" in the spending prerequisites response, the KYC evaluation is complete and the cardholder can proceed to activate their card.

  4. Ongoing Monitoring – After initial KYC completion, make a single call to Get Spending Prerequisites when the user opens your application to check if any actions are required.