smile-identity-core 1.2.0 → 2.0.0

data/examples/document_verification.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'smile-identity-core'
+
+# See https://docs.smileidentity.com/server-to-server/ruby/products/document-verification for
+# how to setup and retrieve configuation values for the WebApi class.
+
+# Initialize
+partner_id = '<Put your partner ID here>'; # login to the Smile Identity portal to view your partner id
+default_callback = '<Put your default callback url here>'
+api_key = '<Put your API key here>'; # copy your API key from the Smile Identity portal
+sid_server = '<0 | 1>'; # Use '0' for the sandbox server, use '1' for production server
+
+connection = SmileIdentityCore::WebApi.new(partner_id, default_callback, api_key, sid_server)
+
+# Create required tracking parameters
+partner_params = {
+  user_id: '<put your unique ID for the user here>',
+  job_id: '<put your unique job ID here>',
+  job_type: 6
+}
+
+# Create image list
+# image_type_id (Integer) - This infers to either a file or a base64 encoded image, but not both.
+# 0 - Selfie image jpg or png (if you have the full path of the selfie)
+# 2 - Selfie image jpg or png base64 encoded (if you have the base64image string of the selfie)
+# 4 - Liveness image jpg or png (if you have the full path of the liveness image)
+# 6 - Liveness image jpg or png base64 encoded (if you have the base64image string of the liveness image)
+# 1 - Front of ID document image jpg or png (if you have the full path of the selfie)
+# 3 - Front of ID document image jpg or png base64 encoded (if you have the base64image string of the selfie)
+# 5 - Back of ID document image jpg or png (if you have the full path of the selfie)
+# 7 - Back of ID document image jpg or png base64 encoded (if you have the base64image string of the selfie)
+image_details = [
+  {
+    image_type_id: '<0 | 2>',
+    image: '<full path to selfie image or base64image string>'
+  },
+  { # Not required if you don't require proof of life (note photo of photo check
+    # will still be performed on the uploaded selfie)
+    image_type_id: '<4 | 6>',
+    image: '<full path to liveness image or base64 image string>'
+  },
+  {
+    image_type_id: '<1 | 3>',
+    image: '<full path to front of id document image or base64image string>'
+  },
+  { # Optional, only use if you're uploading the back of the id document image
+    image_type_id: '<5 | 7>',
+    image: '<full path to back of id document image or base64image string>'
+  }
+]
+
+# The ID Document Information
+id_info = {
+  country: '<2-letter country code>', # The country where ID document was issued
+  id_type: '<id type>' # The ID document type
+}
+
+# Set options for the job
+options = {
+  # Set to true if you want to get the job result in sync (in addition to the result
+  # been sent to your callback). If set to false, result is sent to callback url only.
+  return_job_status: '<true | false>',
+  # Set to true to receive all of the updates you would otherwise have received in your
+  # callback as opposed to only the final result. You must set return_job_status to true to use this flag.
+  return_history: '<true | false>',
+  # Set to true to receive links to the selfie and the photo it was compared to.
+  # You must set return_job_status to true to use this flag.
+  return_image_links: '<true |false>',
+  signature: true
+}
+
+# Submit the job
+connection.submit_job(partner_params, image_details, id_info, options)

data/examples/enhanced_kyc.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'smile-identity-core'
+
+# See https://docs.smileidentity.com/server-to-server/ruby/products/enhanced-kyc for
+# how to setup and retrieve configuation values for the IDApi class.
+
+# Initialize
+partner_id = '<Your partner ID>'; # login to the Smile Identity portal to view your partner id
+api_key = '<Your API key>'; # copy your API key from the Smile Identity portal
+sid_server = '<0 or 1>'; # Use '0' for the sandbox server, use '1' for production server
+
+connection = SmileIdentityCore::IDApi.new(partner_id, api_key, sid_server)
+
+# Create required tracking parameters
+partner_params = {
+  job_id: '<put your unique job ID here>',
+  user_id: '<put your unique ID for the user here>',
+  job_type: 5
+}
+
+# Create ID info
+id_info = {
+  first_name: '<first name>',
+  last_name: '<surname>',
+  country: '<2-letter country code>',
+  id_type: '<id type>',
+  id_number: '<valid id number>',
+  dob: '<date of birth>', # yyyy-mm-dd
+  phone_number: '<phone number>'
+}
+
+# Set the options for the job
+options = {
+  signature: true
+}
+
+# Submit the job
+connection.submit_job(partner_params, id_info, options)

data/examples/example-project/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'dotenv'
+gem 'securerandom'
+gem 'smile-identity-core'

data/examples/example-project/Gemfile.lock

@@ -0,0 +1,25 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    dotenv (2.8.1)
+    ethon (0.15.0)
+      ffi (>= 1.15.0)
+    ffi (1.15.5)
+    rubyzip (1.3.0)
+    securerandom (0.2.0)
+    smile-identity-core (1.2.1)
+      rubyzip (~> 1.2, >= 1.2.3)
+      typhoeus (~> 1.0, >= 1.0.1)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+
+PLATFORMS
+  x86_64-darwin-20
+
+DEPENDENCIES
+  dotenv
+  securerandom
+  smile-identity-core
+
+BUNDLED WITH
+   2.2.6

data/examples/example-project/README.md

@@ -0,0 +1,14 @@
+# Example Project
+
+This project is an example implementation of the Smile Identity Ruby SDK on the server side. The example implements [Enhanced KYC](https://docs.smileidentity.com/products/identity-lookup), [Biometric KYC](https://docs.smileidentity.com/products/biometric-kyc), [Document Verification](https://docs.smileidentity.com/products/document-verification) and [SmartSelfieTM Authentication](https://docs.smileidentity.com/products/biometric-authentication) job types.
+
+## Setup
+
+1. Run `bundle install` to install gem dependencies
+2. Copy sample.env to .env and set secrets as appropriate
+
+```bash
+cp sample.env .env
+```
+
+3. Run `ruby smart_bank.rb` to call the different job types

data/examples/example-project/sample.env

@@ -0,0 +1,4 @@
+SMILE_PARTNER_ID="Put your partner ID here"
+SMILE_JOB_CALLBACK_URL="Put your default callback url here"
+SMILE_API_KEY="Put your API key here"
+SMILE_SERVER_ENVIRONMENT="0 or 1"

data/examples/example-project/smart_bank.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'dotenv/load'
+require 'smile-identity-core'
+require 'securerandom'
+require 'json'
+
+# SmartBank is a fictional banking app
+class SmartBank
+  attr_reader :partner_id, :default_callback, :api_key, :sid_server, :user_id, :job_id
+
+  def initialize
+    # login to the Smile Identity portal to view your partner id
+    @partner_id = ENV['SMILE_PARTNER_ID']
+    # See https://docs.smileidentity.com/server-to-server/ruby/products/biometric-kyc#create-a-callback-endpoint
+    @default_callback = ENV['SMILE_JOB_CALLBACK_URL']
+    @api_key = ENV['SMILE_API_KEY'] # copy your API key from the Smile Identity portal
+    @sid_server = ENV['SMILE_SERVER_ENVIRONMENT'] # Use '0' for the sandbox server, use '1' for production server
+    @user_id = SecureRandom.uuid # your unique ID for the user
+    @job_id = SecureRandom.uuid # your unique job ID
+  end
+
+  # Public: Makes a request to query the Identity Information for an individual using
+  # their ID number from one of our supported ID Types.
+  #
+  # Returns a verification result Hash
+  def perform_enhanced_kyc
+    connection = SmileIdentityCore::IDApi.new(partner_id, api_key, sid_server)
+
+    # Create ID info
+    id_info = {
+      first_name: 'John',
+      last_name: 'Doe',
+      country: 'GH', # 2-letter country code>
+      id_type: 'PASSPORT',
+      id_number: 'G0000000',
+      dob: '1992-12-07', # yyyy-mm-dd
+      phone_number: '00000000000'
+    }
+
+    # Set the options for the job
+    options = {
+      signature: true
+    }
+
+    # Submit the job
+    JSON.parse(connection.submit_job(partner_params(5), id_info, options))
+  end
+
+  # Public: Makes a request to verify the ID information of a user by comparing
+  # the user's SmartSelfie to either the photo of the user on file in an ID authority
+  # database or a photo of their ID card.
+  #
+  # Returns a verification result Hash
+  def perform_biometric_kyc
+    # Create image list
+    image_details = [
+      {
+        image_type_id: SmileIdentityCore::ImageType::SELFIE_IMAGE_FILE,
+        image: '/path/to/selfie_image.jpeg'
+      },
+      { # Not required if you don't require proof of life (note photo of photo check will
+        # still be performed on the uploaded selfie)
+        image_type_id: SmileIdentityCore::ImageType::LIVENESS_IMAGE_FILE,
+        image: '/path/to/liveness_image.jpeg'
+      }
+    ]
+
+    # Create ID number info
+    id_info = {
+      first_name: 'John',
+      last_name: 'Doe',
+      country: 'GH', # 2-letter country code
+      id_type: 'PASSPORT',
+      id_number: 'G0000000',
+      dob: '1992-12-07', # yyyy-mm-dd
+      entered: 'true' # must be a string
+    }
+
+    # Submit the job
+    web_api_connection.submit_job(partner_params(1), image_details, id_info, job_options)
+  end
+
+  # Public: Makes a request to verify the authenticity of Identity documents submitted by users and
+  # confirm that the document actually belongs to the user by comparing the user's selfie to the
+  # photo on the document.
+  #
+  # Returns a verification result Hash
+  def perform_document_verification
+    # Create image list
+    image_details = [
+      {
+        image_type_id: SmileIdentityCore::ImageType::SELFIE_IMAGE_FILE,
+        image: '/path/to/selfie_image.jpeg'
+      },
+      { # Not required if you don't require proof of life (note photo of photo
+        # check will still be performed on the uploaded selfie)
+        image_type_id: SmileIdentityCore::ImageType::LIVENESS_IMAGE_FILE,
+        image: '/path/to/liveness_image.jpeg'
+      },
+      {
+        image_type_id: SmileIdentityCore::ImageType::ID_CARD_IMAGE_FILE,
+        image: '/path/to/front_document_image.jpeg'
+      },
+      { # Optional, only use if you're uploading the back of the id document image
+        image_type_id: SmileIdentityCore::ImageType::ID_CARD_BACK_IMAGE_FILE,
+        image: '/path/to/back_document_image.jpeg'
+      }
+    ]
+
+    # The ID Document Information
+    id_info = {
+      country: 'GH', # The country where ID document was issued
+      id_type: 'PASSPORT' # The ID document type
+    }
+
+    # Submit the job
+    web_api_connection.submit_job(partner_params(6), image_details, id_info, job_options)
+  end
+
+  # Public: Makes a request to verify that an existing user is really the person attempting
+  # to access your system or service. SmartSelfie Authentication can be used as part of a multi-factor
+  # authentication system.
+  #
+  # Returns a verification result Hash
+  def perform_smart_selfie_authentication
+    # Create required tracking parameters
+    partner_params = {
+      user_id: '512c9c37-a689-4959-a620-bed75fb41344', # previously registered user's user_id
+      job_id: SecureRandom.uuid, # new unique job ID
+      job_type: SmileIdentityCore::JobType::SMART_SELFIE_REGISTRATION
+    }
+
+    # Create image list
+    image_details = [
+      {
+        image_type_id: SmileIdentityCore::ImageType::SELFIE_IMAGE_FILE,
+        image: '/path/to/selfie_image.jpeg'
+      },
+      { # Not required if you don't require proof of life
+        # (note photo of photo check will still be performed on the uploaded selfie)
+        image_type_id: SmileIdentityCore::ImageType::LIVENESS_IMAGE_FILE,
+        image: '/path/to/liveness_image.jpeg'
+      }
+    ]
+
+    # Submit the job
+    web_api_connection.submit_job(partner_params, image_details, nil, job_options)
+  end
+
+  private
+
+  def partner_params(job_type)
+    {
+      user_id: user_id,
+      job_id: job_id,
+      job_type: job_type
+    }
+  end
+
+  def web_api_connection
+    return @web_api_connection if defined?(@web_api_connection)
+
+    @web_api_connection = SmileIdentityCore::WebApi.new(partner_id, default_callback, api_key, sid_server)
+  end
+
+  def job_options
+    {
+      # Set to true if you want to get the job result in sync (in addition to the result been sent to your callback).
+      # If set to false, result is sent to callback url only.
+      return_job_status: true,
+      # Set to true to receive all of the updates you would otherwise have received in your callback as opposed to
+      # only the final result. You must set return_job_status to true to use this flag.
+      return_history: false,
+      # Set to true to receive links to the selfie and the photo it was compared to.
+      # You must set return_job_status to true to use this flag.
+      return_image_links: true,
+      signature: true
+    }
+  end
+end
+
+# Enhanced KYC
+smart_bank = SmartBank.new
+enhanced_kyc_response = smart_bank.perform_enhanced_kyc
+enhanced_kyc_response['success'] # => true
+enhanced_kyc_response['result']['PartnerParams']['job_id'] # job_id
+enhanced_kyc_response['result']['PartnerParams']['user_id'] # user_id
+enhanced_kyc_response['result']['PartnerParams']['job_type'] # => 5
+# See https://docs.smileidentity.com/products/for-individuals-kyc/identity-lookup#return-values
+# for the full JSON response interpretation
+
+# Biometric KYC
+bio_kyc_response = smart_bank.perform_biometric_kyc
+bio_kyc_response['success'] # => true
+bio_kyc_response['result']['PartnerParams']['job_id'] # job_id
+bio_kyc_response['result']['PartnerParams']['user_id'] # user_id
+bio_kyc_response['result']['PartnerParams']['job_type'] # => 1
+
+# Document verification
+doc_verification_response = smart_bank.perform_document_verification
+doc_verification_response['success'] # => true
+doc_verification_response['result']['PartnerParams']['job_id'] # job_id
+doc_verification_response['result']['PartnerParams']['user_id'] # user_id
+doc_verification_response['result']['PartnerParams']['job_type'] # => 6
+
+# Smart Selfie Authentication
+smart_selfie_auth_response = smart_bank.perform_smart_selfie_authentication
+smart_selfie_auth_response['success'] # => true
+smart_selfie_auth_response['result']['PartnerParams']['job_id'] # job_id
+smart_selfie_auth_response['result']['PartnerParams']['user_id'] # user_id
+smart_selfie_auth_response['result']['PartnerParams']['job_type'] # => 2
+
+# All jobs submitted with a selfie has the same return values, result codes and texts. For example
+# see https://docs.smileidentity.com/products/for-individuals-kyc/biometric-kyc#return-values.
+# Save the returned user_id and job_id in your DB as you would need them later when you call other services.

data/examples/smart_selfie_authentication.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'smile-identity-core'
+
+# See https://docs.smileidentity.com/server-to-server/ruby/products/smartselfie-tm-authentication for
+# how to setup and retrieve configuation values for the WebApi class.
+
+# Initialize
+partner_id = '<Put your partner ID here>'; # login to the Smile Identity portal to view your partner id
+default_callback = '<Put your default callback url here>'
+api_key = '<Put your API key here>'; # copy your API key from the Smile Identity portal
+sid_server = '<0 | 1>'; # Use '0' for the sandbox server, use '1' for production server
+
+connection = SmileIdentityCore::WebApi.new(partner_id, default_callback, api_key, sid_server)
+
+# Create required tracking parameters
+partner_params = {
+  user_id: '<put previously registered user"s user_id here>',
+  job_id: '<put your unique job ID here>',
+  job_type: 2
+}
+
+# Create image list
+# image_type_id Integer
+# 0 - Selfie image jpg or png (if you have the full path of the selfie)
+# 2 - Selfie image jpg or png base64 encoded (if you have the base64image string of the selfie)
+# 4 - Liveness image jpg or png (if you have the full path of the liveness image)
+# 6 - Liveness image jpg or png base64 encoded (if you have the base64image string of the liveness image)
+image_details = [
+  {
+    image_type_id: '<0 | 2>',
+    image: '<full path to selfie image or base64image string>'
+  },
+  { # Not required if you don't require proof of life (note photo of photo check will
+    # still be performed on the uploaded selfie)
+    image_type_id: '<4 | 6>',
+    image: '<full path to liveness image or base64 image string>'
+  }
+]
+
+# Set options for the job
+options = {
+  # Set to true if you want to get the job result in sync (in addition to the result been sent to your callback).
+  # If set to false, result is sent to callback url only.
+  return_job_status: '<true | false>',
+  # Set to true to receive all of the updates you would otherwise have received in your callback as opposed
+  # to only the final result. You must set return_job_status to true to use this flag.
+  return_history: '<true | false>',
+  # Set to true to receive links to the selfie and the photo it was
+  # compared to. You must set return_job_status to true to use this flag.
+  return_image_links: '<true | false>',
+  signature: true
+}
+
+# Submit the job
+connection.submit_job(partner_params, image_details, nil, options)

data/lib/smile-identity-core/business_verification.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'base64'
+require 'openssl'
+require 'uri'
+require 'typhoeus'
+require_relative 'validations'
+
+module SmileIdentityCore
+  ##
+  # The business verification product lets you search the business registration or
+  # tax information (available in Nigeria only) of a business from one of our supported countries.
+  # For more info visit https://docs.smileidentity.com/products/for-businesses-kyb/business-verification
+  class BusinessVerification
+    include Validations
+
+    BASIC_BUSINESS_REGISTRATION = 'BASIC_BUSINESS_REGISTRATION'
+    BUSINESS_REGISTRATION = 'BUSINESS_REGISTRATION'
+    TAX_INFORMATION = 'TAX_INFORMATION'
+
+    REQUIRED_ID_INFO_FIELD = %i[country id_type id_number].freeze
+
+    ###
+    # Submit business verification
+    # @param [Hash] partner_params the options to create a message with.
+    # @option opts [String] :job_type The job type, this should be 7
+    # @option opts [String] :job_id A unique value generated by you to track jobs on your end.
+    # @option opts [String] :user_id A unique value generated by you.
+    def initialize(partner_id, api_key, sid_server)
+      @partner_id = partner_id.to_s
+      @api_key = api_key
+      @sid_server = sid_server
+      @url = if sid_server !~ URI::DEFAULT_PARSER.make_regexp
+               SmileIdentityCore::ENV::SID_SERVER_MAPPING[sid_server.to_s]
+             else
+               sid_server
+             end
+    end
+
+    # Submit business verification
+    # @param [Hash] partner_params the options to create a job with.
+    # @option opts [String] :job_type The job type, this should be 7
+    # @option opts [String] :job_id A unique value generated by you to track jobs on your end.
+    # @option opts [String] :user_id A unique value generated by you.
+    # @param [Hash] id_info
+    # @option opts [String] :country The job type, this should be 7
+    # @option opts [String] :id_type A unique value generated by you to track jobs on your end.
+    # @option opts [String] :id_number A unique value generated by you.
+    # @option opts [String] :business_type The business incorporation type
+    # bn - business name co - private/public limited it - incorporated trustees
+    def submit_job(partner_params, id_info)
+      @partner_params = validate_partner_params(symbolize_keys(partner_params))
+      @id_info = validate_id_info(symbolize_keys(id_info), REQUIRED_ID_INFO_FIELD)
+
+      if @partner_params[:job_type].to_i != JobType::BUSINESS_VERIFICATION
+        raise ArgumentError, 'Please ensure that you are setting your job_type to 7 to query Business Verification'
+      end
+
+      submit_requests
+    end
+
+    private
+
+    def symbolize_keys(params)
+      params.is_a?(Hash) ? params.transform_keys(&:to_sym) : params
+    end
+
+    def build_payload
+      @payload = generate_signature
+      @payload.merge!(@id_info)
+      add_partner_info
+      add_sdk_info
+      @payload
+    end
+
+    def add_partner_info
+      @payload[:partner_id] = @partner_id
+      @payload[:partner_params] = @partner_params
+    end
+
+    def add_sdk_info
+      @payload[:source_sdk] = SmileIdentityCore::SOURCE_SDK
+      @payload[:source_sdk_version] = SmileIdentityCore::VERSION
+    end
+
+    def generate_signature
+      SmileIdentityCore::Signature.new(@partner_id, @api_key).generate_signature
+    end
+
+    def submit_requests
+      request = Typhoeus::Request.new(
+        "#{@url}/business_verification",
+        method: 'POST',
+        headers: { 'Content-Type' => 'application/json' },
+        body: build_payload.to_json
+      )
+
+      request.on_complete do |response|
+        return response.body if response.success?
+
+        raise "#{response.code}: #{response.body}"
+      end
+      request.run
+    end
+
+    alias setup_requests submit_requests
+  end
+end

data/lib/smile-identity-core/constants/env.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmileIdentityCore
+  module ENV
+    SID_SERVER_MAPPING = {
+      '0' => 'https://testapi.smileidentity.com/v1',
+      '1' => 'https://api.smileidentity.com/v1'
+    }.freeze
+
+    TEST = '0'
+    LIVE = '1'
+  end
+end

data/lib/smile-identity-core/constants/image_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SmileIdentityCore
+  module ImageType
+    SELFIE_IMAGE_FILE = 0
+    ID_CARD_IMAGE_FILE = 1
+    SELFIE_IMAGE_BASE64 = 2
+    ID_CARD_IMAGE_BASE64 = 3
+    LIVENESS_IMAGE_FILE = 4
+    ID_CARD_BACK_IMAGE_FILE = 5
+    LIVENESS_IMAGE_BASE64 = 6
+    ID_CARD_BACK_IMAGE_BASE64 = 7
+  end
+end

data/lib/smile-identity-core/constants/job_type.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmileIdentityCore
+  module JobType
+    BIOMETRIC_KYC = 1
+    SMART_SELFIE_REGISTRATION = 2
+    SMART_SELFIE_AUTHENTICATION = 4
+    BASIC_KYC = 5
+    ENHANCED_KYC = 5
+    DOCUMENT_VERIFICATION = 6
+    BUSINESS_VERIFICATION = 7
+  end
+end