Onfido

The official Ruby library for integrating with the Onfido API.

Documentation can be found at https://documentation.onfido.com

This version uses Onfido API v3.5 and is compatible with Ruby 2.4 onwards. Refer to our API versioning guide for details of which client library versions use which versions of the API.

Installation

Add this line to your application's Gemfile:

gem 'onfido', '~> 2.0.1'

Getting started

Configure with your API token and region:

onfido = Onfido::API.new(
  api_key: ENV['ONFIDO_API_KEY'],
  # Supports :eu, :us and :ca. Previously defaulted to :eu.
  region: :eu
)

All resources share the same interface when making API calls. Use .create to create a resource, .find to find one, and .all to fetch all resources.

For example, to create an applicant:

onfido.applicant.create(
  first_name: 'Test',
  last_name: 'Applicant'
)

Documentation and code examples can be found at https://documentation.onfido.com

Error Handling

There are 3 classes of errors raised by the library, all of which subclass Onfido::OnfidoError:

• Onfido::RequestError is raised whenever Onfido returns a 4xx response
• Onfido::ServerError is raised whenever Onfido returns a 5xx response
• Onfido::ConnectionError is raised whenever a network error occurs (e.g., a timeout)

All 3 error classes provide the response_code, response_body, json_body, type and fields of the error (although for Onfido::ServerError and Onfido::ConnectionError the last 3 are likely to be nil).

def create_applicant
  onfido.applicant.create(params)
rescue Onfido::RequestError => e
  e.type          # => 'validation_error'
  e.fields        # => { "email": { "messages": ["invalid format"] } }
  e.response_code # => '422'
end

Other configuration

Optional configuration options with their defaults:

onfido = Onfido::API.new(
  # ...
  open_timeout: 10,
  read_timeout: 30
)

Verifying webhooks

Each webhook endpoint has a secret token, generated automatically and exposed in the API. When sending a request, Onfido includes a signature computed using the request body and this token in the X-SHA2-Signature header.

You should compare this provided signature to one you generate yourself with the token to verify that a webhook is a genuine request from Onfido.

if Onfido::Webhook.valid?(request.raw_post,
                          request.headers["X-SHA2-Signature"],
                          ENV['ONFIDO_WEBHOOK_TOKEN'])
  process_webhook
else
  render status: 498, text: "498 Token expired/invalid"
end

Read more at https://developers.onfido.com/guide/manual-webhook-signature-verification#webhook-security

Contributing

1. Fork it ( https://github.com/onfido/onfido-ruby/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

More documentation

More documentation and code examples can be found at https://documentation.onfido.com