Skip to main content

Partner Integration Guide

Help to integrate with VerifiMe using the Widget

Written by VerifiMe Support
Updated over a week ago

Partner Integration Guide

By The VerifiMe Team

Jan 15, 2026

Document Information

  • Date: 2025-11-11

  • Prepared by: VerifiMe / Greengate Fintech

  • Purpose: Technical integration guide for VerifiMe identity verification and risk assessment platform

Executive Summary

This document describes the integration of the VerifiMe identity verification and risk assessment platform. It explains:

  • VerifiMe's APIs and what they return

  • VerifiMe's tracking reference system and status lifecycle

  • VerifiMe's two-phase processing model

  • VerifiMe's webhook notification system

  • The data Integration Partner will receive from VerifiMe

This document does NOT prescribe how the Integration Partner should use this data or design their internal processes. Those decisions are entirely up to the Integration Partner based on their business requirements.

VerifiMe System Overview

What VerifiMe Provides

VerifiMe is an identity verification and risk assessment platform that:

  1. Verifies customer identities through document verification, biometric checks, and government database validation

  2. Assesses AML/CTF risk based on configurable rules for each client organisation

  3. Returns results via webhook notifications

Integration Model

Widget-Based Verification:

  • Integration Partner embeds the VerifiMe widget in their application

  • Widget provides QR code and a button for the customer to access the VerifiMe portal

  • Customer completes verification in the VerifiMe customer portal

  • Widget signals when the customer completes data entry

Webhook-Based Results:

  • VerifiMe performs backend processing asynchronously

  • VerifiMe sends risk assessment results via webhook

  • Integration Partner receives structured data about identity verification and risk level

Current VerifiMe Limitations:

  1. User Invite API:

    • Does not accept entityType parameter

    • Cannot restrict verification to a specific entity type

    • Integration Partner or user needs to validate that the entity type verified matches the entity type in their flow (e.g. customer applies as a company and verifies a trust fund)

  2. Tracking Status API:

    • Only returns status: Active, Inactive, Completed

    • Does not return entity type information

  3. Webhook Payload:

    • Does not include explicit entityType field

    • Returns customerName field which contains the entity name

  4. Widget Callback:

    • onSuccess() returns undefined

    • No entity data provided

What Data IS Available

Customer Name Field:
The webhook's customerName field contains the entity name that was verified:

  • For Individuals: Person's full name (e.g., "John Smith")

  • For SMSFs: Superannuation fund name (e.g., "Smith Family Superannuation Fund")

  • For Trusts: Trust name (e.g., "Smith Family Trust")

  • For Companies: Company name (e.g., "Smith Investments Pty Ltd")

Integration Partner can use this field as a proxy for entity validation by matching against expected entity names collected in their application form.

Future Enhancement

VerifiMe plans to add explicit entityType field to webhook payloads and API responses in a future release. Timeline to be determined based on platform development priorities.

Integration Architecture Diagram

The following diagram shows the complete integration flow, including what VerifiMe does and when the Integration Partner must interact with VerifiMe systems.

Key Integration Points

Integration Point 1: Initiate Verification

  • When: Integration Partner decides (typically after the customer completes the application form)

  • Action: Call POST /v1/user/invite

  • Receives: trackingReference for widget initialisation

Integration Point 2: Widget Integration

  • When: Display widget on Integration Partner's page

  • Action: Initialise widget with trackingReference

  • Widget: Automatically polls VerifiMe tracking status endpoint

Integration Point 3: Widget Callback

  • When: Customer completes data entry in VerifiMe portal

  • Trigger: onSuccess() callback fires

  • Meaning: Tracking reference status = "Completed" (customer finished their part)

  • Does NOT mean: Identity verified or risk assessment complete

Integration Point 4: Webhook Delivery

  • When: VerifiMe completes backend processing (1-3 minutes after customer completes)

  • Action: VerifiMe sends POST to the Integration Partner's webhook endpoint

  • Contains: Risk assessment results, customer name, risk level

  • Required: Integration Partner must return HTTP 200 to acknowledge receipt

VerifiMe Tracking Reference System

What is a Tracking Reference?

A tracking reference is a unique identifier (UUID) that represents a customer's verification session. It tracks the customer's progress through data entry in the VerifiMe portal.

Tracking Reference Status Lifecycle

Inactive → Active → Completed

Status: Inactive

  • Meaning: Tracking reference created, customer has not started verification

  • When: Immediately after POST /v1/user/invite returns

  • Customer Action: Has not clicked the widget button or scanned the QR code

Status: Active

  • Meaning: Customer has started the verification process

  • When: Customer clicks the widget button or scans the QR code

  • Customer Action: Currently filling out the verification form in the VerifiMe portal

Status: Completed

  • Meaning: Customer has submitted all required information

  • When: Customer completes and submits verification form

  • Customer Action: Data entry finished, customer can leave

  • Important: This does NOT mean identity is verified or risk assessment is complete

What Tracking Status Does NOT Tell You

❌ Whether identity verification passed or failed

❌ Whether biometric checks were completed

❌ Whether DVS validation succeeded

❌ What the risk assessment result is

❌ What entity type was verified

❌ Whether the verification is approved

Tracking status only indicates customer data entry progress.

When to Check Tracking Status

Widget Checks Automatically:
The VerifiMe widget polls the tracking status endpoint every 3-5 seconds automatically. Integration Partner does not need to poll this endpoint directly.

Manual Polling (Optional):
Integration Partner can optionally poll /v1/user/signup/tracking/{trackingReference}/status

if they need to check status outside of widget context (e.g., if customer returns later).

VerifiMe Two-Phase Processing Model

Critical Understanding: Two Separate Phases

VerifiMe verification consists of two distinct, asynchronous phases:

Phase 1: Customer Data Entry (~2-5 minutes)

  • Customer fills out the form in the VerifiMe portal

  • Customer uploads identity documents

  • Customer completes biometric capture (selfie video)

  • Customer submits information

  • Tracking reference status changes to "Completed"

  • Widget onSuccess() callback fires

  • Customer is redirected back to the Integration Partner application

Phase 2: Backend Processing (~1-3 minutes)

  • Starts after Phase 1 completes

  • Document Verification Service (DVS) validates with government databases

  • The biometric engine performs face matching and liveness detection

  • PEP/Sanctions screening checks watchlists

  • OCR extracts and validates document data

  • Risk assessment engine applies client organisation rules

  • Webhook is sent when complete

The Gap Between Phases

Important: The customer returns to the Integration Partner between Phase 1 and Phase 2.

What This Means for Integration:

  • Widget onSuccess() fires when the customer finishes data entry (end of Phase 1)

  • Webhook arrives 1-3 minutes later (end of Phase 2)

  • Integration Partner must handle this gap appropriately in their UX

VerifiMe Risk Assessment System

Risk Assessment Status

VerifiMe risk assessments have three possible statuses:

PENDING

  • Risk assessment has been queued but not yet started

  • Rare - typically transitions quickly to processing

  • Integration Partner can ignore webhooks with this status

PRELIMINARY

  • Partial risk assessment in progress

  • Not used in standard flow

  • Integration Partner can ignore webhooks with this status

ASSESSED

  • Risk assessment is complete

  • Risk level has been calculated

  • This is the final status

  • Integration Partner should only process webhooks with assessmentStatus = "ASSESSED"

Risk Levels

VerifiMe calculates one of four risk levels:

Risk Level

Description

LOW

Minimal risk detected based on assessment rules

MEDIUM

Moderate risk factors present

HIGH

Significant risk factors identified

EXTREME

Maximum risk level - multiple serious risk factors

Note: Risk levels are determined by the client organisation's configured rules in VerifiMe. Different clients may have different thresholds and criteria.

What Risk Assessment Includes

VerifiMe's risk assessment considers:

  • Identity verification results (DVS, biometric, OCR)

  • PEP (Politically Exposed Person) screening

  • Sanctions list checking

  • Adverse media screening

  • Client organisation's custom risk rules

  • Historical patterns and behaviour (if applicable)

When Risk Assessment Runs

Risk assessment runs automatically when:

  1. Customer identity status reaches "Verified"

  2. All verification checks (DVS, biometric, PEP/sanctions) have been completed

  3. The customer has granted permission to client organisation

Timeline: Typically 1-3 minutes after the customer completes data entry.

VerifiMe API Reference

POST /v1/user/invite

Purpose: Create a tracking reference for customer verification

Endpoint: </v1/user/invite>

Authentication: None required (public endpoint)

Request Body:

Request Parameters:

Parameter

Type

Required

Description

email

String

Yes

Customer's email address

code

String

Yes

Integration Partner's VerifiMe organization code (provided during onboarding)

referenceData

String

No

Opaque string returned in webhook metadata field (use for correlation)

Response:

Response Fields:

Field

Type

Description

trackingReference

String (UUID)

Unique identifier for this verification session

inviteUrl

String (URL)

Direct link to VerifiMe customer portal for this session

qrCodeUrl

String (URL)

QR code image URL that encodes the inviteUrl

Important: referenceData Field

The referenceData parameter is critical for webhook correlation. Whatever string you pass here will be returned in the webhook's metadata field. Use this to link the webhook back to your application (e.g., application ID, customer ID, etc.).

GET /v1/user/signup/tracking/{trackingReference}/status

Purpose: Check tracking reference status (customer data entry progress)

Endpoint: </v1/user/signup/tracking/{trackingReference}/status>

Authentication: None required (public endpoint)

Path Parameters:

Parameter

Type

Description

trackingReference

String (UUID)

The tracking reference from /v1/user/invite

Response:

Response Fields:

Field

Type

Possible Values

status

String

"Inactive", "Active", "Completed"

Status Meanings:

  • Inactive: Customer has not started (hasn't clicked button/scanned QR)

  • Active: Customer is currently in the VerifiMe portal

  • Completed: Customer has submitted all information

Note: This endpoint only tracks customer data entry. It does NOT provide:

  • Identity verification results

  • Risk assessment results

  • Entity type information

  • Approval status

Widget Polling:
The VerifiMe widget automatically polls this endpoint. Integration Partner does not need to call it unless checking status outside widget context.

VerifiMe Widget

Widget Purpose

The VerifiMe widget provides:

  • Visual QR code display for mobile verification

  • "Verify with VerifiMe" button for desktop flow

  • Automatic polling of tracking reference status

  • Status transitions and visual feedback

  • Callback when the customer completes data entry

Widget Initialization

HTML Container:

JavaScript:

Parameters:

Parameter

Type

Description

selector

String

CSS selector for container element

trackingReference

String

UUID from /v1/user/invite response

options.onSuccess

Function

Called when tracking status reaches "Completed"

options.onError

Function

Called if technical error occurs

Widget Callbacks

onSuccess() Callback

Triggers When:

  • Tracking reference status changes to "Completed"

  • The customer has submitted all information in the VerifiMe portal

  • Customer is being redirected back to the Integration Partner application

Function Signature:

What It Means:

✅ Customer completed data entry (Phase 1 complete)

✅ Customer has returned to Integration Partner application

❌ Does NOT mean identity is verified

❌ Does NOT mean risk assessment is complete

❌ Does NOT mean application is approved

What It Does NOT Provide:

  • No entity type information

  • No verification results

  • No risk assessment results

  • No approval status

  • Currently returns undefined (no parameters)

onError() Callback

Triggers When:

  • Technical error occurs (network failure, API error)

  • The widget cannot communicate with VerifiMe servers

Function Signature:

Widget Behavior

Automatic Status Polling:
The widget automatically polls /v1/user/signup/tracking/{trackingReference}/status

every 3-5 seconds to detect status changes.

Status-Based Display:

  • Inactive: Shows QR code and "Verify with VerifiMe" button

  • Active: Shows "Verifying with VerifiMe" message with spinner

  • Completed: Triggers onSuccess() callback

  • Error: Triggers onError() callback

User Flow:

  1. User sees QR code or button

  2. User clicks the button or scans the QR code

  3. User redirected to VerifiMe portal

  4. User completes verification form

  5. User redirected back to Integration Partner

  6. Widget detects "Completed" status

  7. onSuccess() callback fires

VerifiMe Webhook System

Webhook Overview

VerifiMe sends webhooks to notify the Integration Partner when risk assessments are complete. Webhooks are sent asynchronously after backend processing completes.

Webhook Configuration

During Onboarding:
Integration Partner must provide a publicly accessible HTTPS endpoint URL to VerifiMe.

Example: <https://api.IntegrationPartner.com.au/webhooks/verifime>

Requirements:

  • Must be HTTPS (SSL/TLS required)

  • Must be publicly accessible from internet

  • Must return HTTP 200 within 10 seconds

  • Must handle POST requests

Webhook Security

HMAC Signature Verification:
Every webhook includes an HMAC-SHA256 signature in the request header. Integration Partner must verify this signature to ensure webhook authenticity.

Headers:

Header

Description

X-VerifiMe-Signature

HMAC-SHA256 hex digest of request body

X-VerifiMe-Version

Webhook schema version (currently "1")

Content-Type

application/json

Verification Process:

  1. Receive raw request body (do not parse JSON yet)

  2. Compute HMAC-SHA256 hash of raw body using your shared secret

  3. Compare the computed hash with X-VerifiMe-Signature header

  4. Reject request with HTTP 401 if signatures don't match

  5. Only process the webhook if the signature is valid

Shared Secret:
VerifiMe will provide a unique shared secret key during onboarding. This key must be stored securely and never exposed publicly.

Important: Always use constant-time comparison when validating signatures to prevent timing attacks.

Webhook Event: RISK_ASSESSMENT_UPDATED

Event Type: RISK_ASSESSMENT_UPDATED

When Sent:

  • After identity verification completes (identity status: Verified)

  • After the risk assessment engine finishes the calculation

  • Typically 1-3 minutes after the customer completes data entry

  • Only when assessmentStatus reaches "ASSESSED"

Payload Structure:

Payload Fields:

Field

Type

Description

eventId

String (UUID)

Unique identifier for this webhook event (use for idempotency)

eventName

String

Always "RISK_ASSESSMENT_UPDATED" for this event type

customerName

String

Entity name from verification (Individual: person name, SMSF: fund name, etc.)

assessmentStatus

String

Risk assessment status: "PENDING", "PRELIMINARY", or "ASSESSED"

riskLevel

String or null

Risk level: "LOW", "MEDIUM", "HIGH", "EXTREME", or null if pending

assessmentPortalUrl

String

URL to view full assessment in VerifiMe client portal

eventTimestamp

String

ISO 8601 timestamp of when the assessment was completed

metadata

String

The referenceData value from /v1/user/invite request

Field Details:

customerName:

  • Contains the entity name that was verified

  • For Individuals: Full name (e.g., "John Smith")

  • For SMSFs: Fund name (e.g., "Smith Family Superannuation Fund")

  • For Trusts: Trust name (e.g., "Smith Family Trust")

  • For Companies: Company name (e.g., "Smith Investments Pty Ltd")

  • Use as a proxy for entity type validation

assessmentStatus:

  • PENDING: Assessment queued (rare, typically brief)

  • PRELIMINARY: Partial assessment (not used in standard flow)

  • ASSESSED: Assessment complete (recommended to only process this status)

riskLevel:

  • Only present when assessmentStatus = "ASSESSED"

  • Determined by the VerifiMe risk assessment engine based on the client organisation's configured rules

  • Different clients may have different risk thresholds

metadata:

  • Returns the exact string passed in referenceData parameter of /v1/user/invite

  • Use this to correlate the webhook with your application/customer record

Webhook Response Requirements

Success Response:

Required:

  • Must return HTTP 200 status code

  • Should return within 10 seconds

  • Response body is optional but recommended for logging

Error Responses:
If Integration Partner returns any status code other than 200, VerifiMe will consider the webhook delivery failed and will retry.

Retry Behavior:

  • Automatic retry with exponential backoff

  • Retries continue for up to 24 hours

  • After 24 hours, the delivery is abandoned

Important:

  • Return HTTP 200 even if there are business logic issues (e.g., application not found)

  • Only return non-200 for technical failures (server down, etc.)

  • Process webhook asynchronously after returning 200

Webhook Best Practices

1. Idempotency:
Use the eventId field to detect duplicate deliveries. Store processed event IDs and skip processing if they have already been seen.

2. Signature Verification:
Always verify the HMAC signature before processing webhook data. Reject invalid signatures immediately.

3. Asynchronous Processing:
Return HTTP 200 quickly, then process webhook data asynchronously. Don't make VerifiMe wait for your business logic.

4. Filter by Status:
Recommended only to process webhooks where assessmentStatus = "ASSESSED". Ignore PENDING and PRELIMINARY statuses.

5. Error Handling:
Log all webhook processing errors but still return HTTP 200 to prevent retries for business logic issues.

6. Monitoring:
Monitor webhook endpoint uptime and alert on delivery failures. Missing webhooks will delay processing.

Integration Checklist

Prerequisites

  • Obtain the VerifiMe organisation code from the VerifiMe onboarding team

  • Obtain the webhook shared secret from VerifiMe onboarding team

  • Determine when in your application flow to initiate verification

API Integration

  • Implement call to POST /v1/user/invite

  • Store returned trackingReference for widget initialisation

  • Pass the application identifier in the referenceData parameter

Widget Integration

  • Add VerifiMe widget script to your page

  • Initialise widget with trackingReference

  • Implement onSuccess() callback handler

  • Implement onError() callback handler

  • Decide what to show the customer when onSuccess() fires

Webhook Integration

  • Create publicly accessible HTTPS endpoint

  • Implement HMAC signature verification

  • Implement idempotency checking using eventId

  • Parse webhook JSON payload

  • Extract metadata field to correlate with your application

  • Return HTTP 200 within 10 seconds

  • Process webhook data asynchronously

Testing

  • Test full flow in VerifiMe staging environment

  • Test webhook signature verification

  • Test duplicate webhook handling (same eventId twice)

  • Test webhook retry behaviour (return non-200 status)

  • Test various risk levels (LOW, MEDIUM, HIGH, EXTREME)

  • Test various entity types (Individual, SMSF, Trust, Company)

Monitoring

  • Set up webhook endpoint monitoring and alerting

  • Monitor webhook delivery success rate

  • Alert if the webhook is not received within the expected timeframe

  • Log all webhook payloads for debugging

Testing & Staging Environment

VerifiMe provides a staging environment for integration testing. We strongly advise you test in the staging environment as you can use test data.

Differences from Production:

  • Staging does not perform real DVS checks with government databases

  • Staging may require manual completion of verification steps

  • Staging risk assessments use test rules

  • Staging webhooks use a separate shared secret

Contact VerifiMe support for:

  • Staging environment access

  • Staging organisation code

  • Staging webhook secret

  • Test data and scenarios

Core Components and Environments

Integrating with VerifiMe involves working with these core components:

The Client Portal

  1. Live (production) - https://client-portal.verifime.com

  2. Test (staging) - https://client-portal.stage.verifime.com

The Customer Portal

  1. Live (production) - https://portal.verifime.com

  2. Test (staging) - https://portal.stage.verifime.com

API Endpoints

  1. Live - https://api.prod.verifime.com

  2. Test - https://api.stage.verifime.com

Open API specification is available on request.

Widget CDN

  1. Live - https://widget.static.prod.verifime.com

  2. Test - https://widget.static.stage.verifime.com

Summary

What VerifiMe Provides

  1. Identity Verification:

    • Document verification (DVS with government databases)

    • Biometric verification (face matching, liveness)

    • PEP/Sanctions screening

    • OCR document extraction

  2. Risk Assessment:

    • Configurable rules engine

    • Four risk levels: LOW, MEDIUM, HIGH, EXTREME

    • Automatic calculation after identity verification

  3. Integration APIs:

    • POST /v1/user/invite - Initiate verification

    • GET /tracking/{ref}/status - Check customer progress

    • Webhook - Receive risk assessment results

  4. Widget:

    • Embeddable QR code and button

    • Automatic status polling

    • Callback when customer completes

What Data Integration Partner Receives

From /v1/user/invite:

  • trackingReference (for widget initialisation)

  • inviteUrl (direct portal link)

  • qrCodeUrl (QR code image)

From Widget Callback:

  • Signal that the customer has completed data entry

  • No additional data (callback returns undefined)

From Webhook:

  • customerName (entity name - proxy for entity type)

  • riskLevel (LOW/MEDIUM/HIGH/EXTREME)

  • assessmentStatus (PENDING/PRELIMINARY/ASSESSED)

  • metadata (your application identifier)

  • eventTimestamp (when assessment completed)

Key Understanding

  1. Two-Phase Process:

    • Phase 1: Customer data entry (ends with widget onSuccess)

    • Phase 2: Backend processing (ends with webhook delivery)

    • Gap of 1-3 minutes between phases

  2. Tracking Status vs Risk Assessment:

    • Tracking status tracks customer data entry only

    • Risk assessment status delivered via webhook

    • These are separate and asynchronous

  3. Entity Type Limitation:

    • No explicit entityType field is currently available

    • Use customerName field as proxy

    • Future enhancement planned

  4. Webhook is the Final Result:

    • Widget signals customer completion

    • Webhook delivers verification and risk assessment results

    • Integration Partner decides what to do with the data

Contact & Support

Document Version: 1.1
​Last Updated: 13 Nov 2025
​Document Type: Integration Technical Specification

Related Articles
Step 7: Permissions and Consent to Service Providers
PEP and Sanctions Screening
Configuring Mitigation Templates in VerifiMe
Frequently Ask Questions
Return Path URL Configuration Guide
Did this answer your question?