Didit.me (KYC)

Integrate WPsigner with Didit.me to require identity verification (KYC) before signers can access a document. Signers verify their identity by uploading a government-issued ID, taking a selfie, and passing a liveness check — all before they see the first signature field.

Note

This is a two-step activation: first configure API credentials on the Integrations page, then enable the KYC requirement on the Security & Compliance page.

---

Features

Feature	Description
ID Document Verification	Supports passports, national IDs, and driver’s licenses
Selfie Matching	Compares a live selfie to the photo on the ID document
Liveness Detection	Prevents spoofing with passive liveness checks
Webhook Callbacks	Real-time verification status updates via webhooks
Per-Signer Tracking	KYC status stored per signer (Pending, Approved, Declined)
Automatic Language	Verification UI adapts to the signer’s WordPress locale
Encrypted Credentials	API key and webhook secret encrypted with AES-256-GCM

---

Prerequisites

• WPsigner 2.3.0+
• A Didit.me Business account
• A configured verification Workflow in the Didit console
• An API Key and Webhook Secret from the Didit console

---

Step 1: Create a Didit Workflow

1. Go to the Didit Business Console
2. Navigate to Workflows and create a new workflow
3. Configure the verification steps you want:
   • ID Document — require a government-issued ID
   • Selfie — require a selfie to match against the ID photo
   • Liveness — enable passive liveness detection
4. Save the workflow and copy the Workflow ID

---

Step 2: Get Your API Credentials

1. In the Didit Business Console, go to Settings → API Keys
2. Create a new API key or copy an existing one
3. Copy the API Key
4. Go to Settings → Webhooks and copy your Webhook Secret

Caution

The webhook secret is used to verify that incoming webhook requests actually come from Didit. Without it, WPsigner rejects all webhook callbacks as a security precaution.

---

Step 3: Configure WPsigner

Add API Credentials

1. Go to WPsigner → Integrations in your WordPress admin
2. Find Didit.me under Identity Verification and click Configure
3. Enter your:
   • API Key
   • Workflow ID
   • Webhook Secret
4. Click Test Connection to verify your credentials
5. Click Save Settings

Set the Webhook URL

Copy the webhook URL shown on the settings page and add it to your Didit console:

https://your-site.com/?wps_didit_webhook=1

1. In the Didit Business Console, go to Webhooks
2. Add the URL above as a webhook endpoint
3. Select the events to listen for (session completed, session declined)

Enable KYC Requirement

1. Go to WPsigner → Settings → Security & Compliance
2. Enable Require Identity Verification (KYC)
3. Save the settings

The toggle on the Security & Compliance page is separate from the API credentials. You need both: credentials configured on the Integrations page AND the requirement enabled on Security & Compliance.

---

How It Works

Signer Opens Signing Page
        ↓
KYC Check: Has signer been verified?
        ↓ No
Redirect to Didit Verification
        ↓
Signer uploads ID + selfie + liveness
        ↓
Didit processes verification
        ↓
Webhook callback updates signer status
        ↓
Signer redirected back → Can now sign

Verification Flow

1. When a signer opens a document that requires KYC, WPsigner checks their verification status.
2. If not verified, WPsigner creates a Didit session via the API, passing the signer’s name and email.
3. The signer is redirected to Didit’s verification page where they:
   • Upload a photo of their government ID
   • Take a live selfie
   • Pass the liveness check
4. Didit processes the verification and sends a webhook to WPsigner.
5. WPsigner updates the signer’s kyc_status to Approved or Declined.
6. The signer is redirected back to the signing page and can proceed to sign.

KYC Statuses

Status	Meaning
Pending	Session created, waiting for signer to verify
Approved	Identity verified — signer can sign
Declined	Verification failed — signer cannot sign

---

Signer Experience

The KYC step appears before the signing page. Signers see a clear prompt explaining that identity verification is required:

1. Signer clicks the signing link in their email
2. Instead of the signing page, they see a verification prompt
3. They click “Verify Identity” which redirects to Didit
4. After completing verification, they’re sent back to the signing page
5. The signing page loads normally — they can now sign

Tip

Signers only need to verify once per document. If they’ve already been verified for a specific document, they go straight to the signing page on subsequent visits.

---

Data Storage

Data	Storage Location
KYC status	wps_signers table: kyc_status column
Session ID	wps_signers table: kyc_session_id column
Verification URL	wps_signers table: kyc_data (JSON)
Verified timestamp	wps_signers table: kyc_verified_at (UTC)
API credentials	wp_options table (encrypted with AES-256-GCM)

---

Security

Feature	Implementation
API Key	Encrypted with AES-256-GCM at rest
Webhook Secret	Encrypted with AES-256-GCM at rest; used to validate incoming webhooks
Webhook Validation	Fail-closed: rejects all webhooks if secret is not configured
Session Creation	Rate limited, nonce verified, capability checked
Status Checks	Only authenticated AJAX requests with valid nonce
PII Handling	Verification data stays on Didit’s servers; WPsigner only stores status and session ID

---

Troubleshooting

”Test Connection” fails

1. Verify your API Key is correct (copy it again from the Didit console)
2. Ensure your server can make outbound HTTPS requests to verification.didit.me
3. Check that your Didit account is active and not suspended

Webhook not updating signer status

1. Verify the webhook URL is correctly set in the Didit console: https://your-site.com/?wps_didit_webhook=1
2. Confirm your Webhook Secret matches between Didit and WPsigner
3. Check that your site is publicly accessible (Didit cannot reach localhost)
4. Enable WP_DEBUG and check debug.log for entries starting with WPsigner Didit

Signer stuck on “Pending”

1. The signer may not have completed the verification process — ask them to check for a pending session
2. Check if the webhook was received (look in debug logs)
3. Try creating a new session by having the signer revisit the signing link

”Workflow ID not configured”

Go to WPsigner → Integrations → Didit.me and enter your Workflow ID from the Didit Business Console.

---

Next Steps

• Audit Trails — KYC verification events are logged in the audit trail
• Digital ID — Add cryptographic identity with PKI certificates
• Compliance — How KYC fits into eIDAS, ESIGN, and other regulations