Case - Callback

The callback delivers the final snapshot of the verification workflow once it reaches a terminal state.

Endpoint Configuration: callback_url

📘
Important:
This callback is only sent for verification sessions that are NOT linked to a user profile.

When It's Triggered

Verification workflow reaches a terminal state:

APPROVED: All checks passed
DECLINED: One or more checks failed
MANUAL_REVIEW: Requires human review
FAILED: Technical error in processing

Payload Structure: UserVerificationResultPayload

{
  "verification_session_id": "vs_abc123",
  "template_id": "tmpl_kyc_basic",
  "client_reference_id": "user_12345",
  "client_reference_data": {
    "user_tier": "premium",
    "referral_source": "mobile_app"
  },
  "aiprise_summary": {
    "decision": "APPROVED",
    "status": "COMPLETED",
    "warning_codes": [],
    "reasons": [],
    "notes": "All checks passed successfully"
  },
  "status": "COMPLETED",
  "created_at": 1702345678000,
  "status_reasons": [],
  "user_input": {
    "user_data": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15",
      "email": "[email protected]",
      "phone": "+1234567890",
      "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      }
    },
    "additional_user_info": {
      "id_document_front_url": "https://presigned-url/id-front.jpg",
      "id_document_back_url": "https://presigned-url/id-back.jpg",
      "selfie_url": "https://presigned-url/selfie.jpg"
    }
  },
  "id_info": {
    "document_type": "DRIVERS_LICENSE",
    "issuing_country": "US",
    "document_number": "D1234567",
    "expiry_date": "2028-01-15",
    "authenticity": {
      "result": "PASS",
      "checks": [
        {
          "check_name": "hologram_verification",
          "status": "PASS"
        },
        {
          "check_name": "mrz_validation",
          "status": "PASS"
        }
      ]
    },
    "extracted_data": {
      "first_name": "JOHN",
      "last_name": "DOE",
      "date_of_birth": "1990-01-15",
      "address": "123 MAIN ST, NEW YORK, NY 10001"
    }
  },
  "face_match_info": {
    "result": "PASS",
    "match_score": 0.96,
    "threshold": 0.85,
    "comparison_details": {
      "id_photo_url": "https://presigned-url/id-face.jpg",
      "selfie_url": "https://presigned-url/selfie.jpg"
    }
  },
  "face_liveness_info": {
    "result": "PASS",
    "liveness_score": 0.98,
    "checks": [
      {
        "check_name": "blink_detection",
        "status": "PASS"
      },
      {
        "check_name": "motion_analysis",
        "status": "PASS"
      }
    ]
  },
  "aml_info": {
    "result": "CLEAR",
    "screening_status": "COMPLETED",
    "matches": [],
    "monitoring_enabled": true,
    "next_monitoring_run": "2024-02-01T00:00:00Z"
  },
  "fraud_insights": {
    "overall_risk_score": 12,
    "risk_level": "LOW",
    "signals": [
      {
        "signal_type": "device_fingerprint",
        "risk_score": 5,
        "description": "Device has been seen before"
      },
      {
        "signal_type": "geolocation",
        "risk_score": 7,
        "description": "Location matches declared address"
      }
    ]
  },
  "lookup_info": [
    {
      "provider": "government_registry",
      "status": "MATCH",
      "verified_fields": ["name", "date_of_birth", "address"]
    }
  ],
  "risk_info": {
    "risk_score": 15,
    "risk_tier": "LOW",
    "contributing_factors": [
      {
        "factor": "first_time_user",
        "weight": 10
      },
      {
        "factor": "high_value_transaction_intent",
        "weight": 5
      }
    ]
  },
  "aml_monitoring_info": {
    "enabled": true,
    "frequency": "DAILY",
    "next_run_at": "2024-02-01T00:00:00Z"
  }
}

Key Payload Sections

Section	Description
`aiprise_summary`	High-level decision, status, and reasons
`user_input`	Submitted user data and document URLs
`id_info`	ID document verification results and extracted data
`face_match_info`	Face comparison between ID and selfie
`face_liveness_info`	Liveness detection results
`aml_info`	AML screening results and monitoring status
`fraud_insights`	Fraud detection signals and risk scores
`lookup_info`	External data verification results
`risk_info`	Overall risk assessment

Decision Flow

callback_url received
    ↓
Verify HMAC signature
    ↓
Parse aiprise_summary.decision
    ↓
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│    APPROVED     │    DECLINED     │  MANUAL_REVIEW  │     FAILED      │
└────────┬────────┴────────┬────────┴────────┬────────┴────────┬────────┘
         ↓                 ↓                 ↓                 ↓
   Grant access      Deny access      Queue for review   Retry/notify
   Enable features   Notify user      Notify reviewer    Technical team
   Update status     Log reason       Display case       Error handling