KYC Status Events

kyc.status.changed

Content-Type: application/json
X-Timestamp: 1767711032
X-Signature: 9af85e3e50d7a5c0ee1dcc519a063f272efc8a0d4c75a55eb0c1296e45e13564

{
  "api_version": "v1",
  "event_id": "c386021a-d7a5-4aff-8924-4374f1d1d84f",
  "event_category": "kyc",
  "event_type": "kyc.status.changed",
  "user_id": "ecf74983-b52f-40ff-8a4c-aa052748459b",
  "event_object_id": "ecf74983-b52f-40ff-8a4c-aa052748459b",
  "event_object_status": "completed",
  "event_object_changes": {
    "status": ["pending", "completed"]
  },
  "event_object": {
    "status": "completed",
    "failure_code": null,
    "failure_reason": null
  },
  "occurred_at": "2026-01-06T14:50:31.481Z"
}

{
  "api_version": "v1",
  "event_id": "d486021a-e8b6-5bff-9035-5485f2e2e95g",
  "event_category": "kyc",
  "event_type": "kyc.status.changed",
  "user_id": "ecf74983-b52f-40ff-8a4c-aa052748459b",
  "event_object_id": "ecf74983-b52f-40ff-8a4c-aa052748459b",
  "event_object_status": "failed",
  "event_object_changes": {
    "status": ["pending", "failed"]
  },
  "event_object": {
    "status": "failed",
    "failure_code": "103",
    "failure_reason": "Person showing the document does not appear to match document photo"
  },
  "occurred_at": "2026-01-06T15:02:47.000Z"
}

async function handleKycEvent(event: WebhookEvent): Promise<void> {
  const { user_id, user_external_id, event_object } = event;
  const { status, failure_code, failure_reason } = event_object;

  switch (status) {
    case 'completed':
      // Grant access, activate card, etc.
      await activateUser(user_id);
      break;

    case 'failed':
      // Notify the user and log the failure reason
      await notifyUserKycFailed(user_external_id, failure_code, failure_reason);
      break;

    case 'edd_required':
      // Prompt the user to complete Enhanced Due Diligence
      await requestEdd(user_external_id);
      break;

    case 'pending':
    case 'kyc_checked':
    case 'edd_submitted':
      // Informational — no action required
      break;
  }
}