README

The Vouchsafe PHP library provides convenient, typed access to the Vouchsafe API for applications written in PHP.

Requirements

PHP 7.2.5 or better.

Installation

composer require vouchsafe/vouchsafe-php

Usage

The SDK needs a client ID and secret, which is available in the Vouchsafe dashboard. Replace the values below:

<?php
require __DIR__ . '/vendor/autoload.php';

use Vouchsafe\VouchsafeClient;

$client = new VouchsafeClient([
  'client_id' => 'YOUR_CLIENT_ID',
  'client_secret' => 'YOUR_SANDBOX_SECRET',
]);

// Request a verification
$res = $client->requestVerification([
  'email' => 'foo@bar.com'
]);

echo $res->getId();
echo $res->getUrl();

List verifications

$list = $client->listVerifications(['status' => 'InProgress']);

Get a specific verification

$verification = $client->getVerification(['id' => 'abc123']);

List flows

$flows = $client->listFlows();

Verify a photo ID

Extract and validate a photo ID (passport, national ID, driving licence, PASS card, or unfamiliar photo ID), optionally face-matching it against a selfie. Image fields are passed as file paths:

$result = $client->verifyPhotoId([
  'sub_type'     => 'DrivingLicence', // Passport | NationalId | DrivingLicence | PASSCard | UnfamiliarPhotoId
  'front'        => '/path/to/licence-front.jpg',
  'country_code' => 'GB',             // DrivingLicence only
  // 'back'      => '/path/to/back.jpg',   // NationalId only
  // 'face_scan' => '/path/to/selfie.jpg', // Optional selfie to face-match
]);

echo $result['outcome']; // 'pass' or 'fail'
echo $result['extracted_details']['first_name'];

Sandbox mode

Use a sandbox rather than a live client secret to activate sandbox mode on methods that support it.

Re-authentication

The client will automatically cache your access token and insert it into every request, and fetch a new one upon expiry.

If a request fails with a 401 Unauthorised error, it will fetch a new access token and retry once before throwing an error.

Use one client instance

For best performance, you should create one client per request/process.

The client caches the access token in memory for the life of that process.

If you run multiple instances of your app, each instance can authenticate on its own and cache its own access token.

Handling errors

Wrapper methods throw Vouchsafe\VouchsafeApiError on non-2xx responses.

It includes the HTTP status code and the error body:

try {
  $res = $client->getVerification(['id' => 'non-existent']);
} catch (\Vouchsafe\VouchsafeApiError $e) {
  echo $e->statusCode . ' ' . $e->getMessage();
}

Development

See the contribution guidelines for this project

Contributions including issues and pull requests are welcome.

To run the project locally, clone the repo and run:

composer install
make generate # regenerate the OpenAPI files from spec

Further reading

• Developer docs
• Full API endpoint reference
• 3-minute video guide