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();

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.

Each time a new access token is requested using the same client credentials, it invalidates the old one.

Having multiple clients sharing the same credentials can lead to:

• over-writing each other's tokens
• unnecessary retries and re-authentications.

For high-concurrency use cases, you should store the access token in a shared key-value store instead.

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