ID Verification Integration

As of v1.0.32, the Direct Debit mandate form includes a mandatory identity verification step powered by a third-party provider (Onfido or Veriff). This step protects against fraud by confirming a tenant's identity before a mandate can be submitted.

---

How It Works

1. Mandate Form — Step 6

During the mandate setup flow, Step 6 presents the tenant with an ID verification experience. Depending on configuration, this is delivered as either:

• Embedded SDK — the provider's verification widget is rendered inline within the mandate form page.
• Redirect — the tenant is redirected to the provider's hosted verification page and returned to the mandate form on completion.

The tenant completes their identity check (typically: document upload or capture, and a liveness/selfie check) directly within this step.

2. Webhook on Completion

Once the provider completes processing the verification, it sends a webhook callback to the service. The service:

1. Validates the incoming webhook (signature verification).
2. Extracts the verification result.
3. Stores the result against the associated mandate record.

3. Verification Result States

Status	Meaning
passed	The tenant's identity was successfully verified. The mandate may proceed.
failed	Verification was unsuccessful. The mandate is blocked from submission.
pending	The provider has not yet returned a final decision. Submission is blocked until a final result is received.

4. Submission Gating

The mandate submission step enforces the following rule:

• passed → mandate can be submitted.
• failed → mandate submission is blocked. The tenant is informed and cannot proceed.
• pending → mandate submission is blocked until the provider delivers a final result via webhook.

This prevents unverified or fraudulently submitted mandates from entering the BACS collection cycle.

---

Mandate Detail API

The mandate detail endpoint now includes an id_verification field in its response. See the API Reference for full schema details.

Example response excerpt:

{
  "id": "mnd_abc123",
  "status": "pending_submission",
  "id_verification": {
    "status": "passed",
    "provider": "onfido",
    "verified_at": "2025-06-01T10:45:00Z"
  }
}

Possible values for id_verification.status: passed, failed, pending.

---

Configuration

The ID verification provider is configured at the service level. The following must be set up before the feature is active:

• Provider selection — Onfido or Veriff (set in service configuration).
• API credentials — Provider API key/secret for SDK initialisation and webhook validation.
• Webhook endpoint — Register the service's webhook URL with the provider's dashboard so result callbacks are delivered correctly.
• SDK mode — Choose between embedded or redirect delivery mode.

---

Tenant Experience

1. Tenant reaches Step 6 of the mandate form.
2. The ID verification SDK loads (embedded or redirect).
3. Tenant completes document and liveness checks.
4. On completion, the provider sends a result webhook to the service.
5. If passed, the tenant can proceed to the confirmation step.
6. If failed or pending, the tenant is shown an appropriate message and cannot submit the mandate.

---

Notes

• If the provider webhook is delayed, the mandate will remain in a pending verification state and submission will be blocked until the callback is received.
• Failed verifications are stored and linked to the mandate record for audit purposes.
• The verification result is visible to agents via the mandate detail API.