Ruby SDK for KYC, AML and Transactions

The official Didit gem for Ruby. It needs Ruby 3.1 or later and uses net/http from the standard library. See the server SDKs overview for what every SDK shares.

Install

gem install didit-sdk

The gem is didit-sdk on RubyGems. Its source and changelog are in didit-protocol/sdk-ruby on GitHub. Or add gem "didit-sdk" to your Gemfile and run bundle install. Load it with require "didit".

Configure the client

Didit::Client.new reads DIDIT_API_KEY from the environment. Pass keywords to override it, or to set the organization and application ids that application-scoped calls (cases, networks, regulatory reports) need. Request fields are keyword arguments with the API’s own names; responses are objects with a reader per field, [:field] and to_h.

require "didit"

didit = Didit::Client.new(
  api_key: ENV["DIDIT_API_KEY"],
  organization_id: ENV["DIDIT_ORGANIZATION_ID"],
  application_id: ENV["DIDIT_APPLICATION_ID"],
  timeout: 30,
  max_retries: 2
)

# Options for a single call.
decision = didit.with_options(timeout: 5, max_retries: 0).sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
puts decision.status

Create a session

Create a verification session for a workflow and send your user to its URL.

require "didit"

didit = Didit::Client.new

session = didit.sessions.create(
  workflow_id: "11111111-2222-3333-4444-555555555555",
  vendor_data: "user-123",
  callback: "https://example.com/verification/done"
)
puts session.url

Read the decision

When the user finishes (or when the webhook arrives), read the decision. Every feature result is a list with one entry per workflow node.

require "didit"

didit = Didit::Client.new

decision = didit.sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
puts decision.status
(decision.id_verifications || []).each do |verification|
  puts verification.status
end

Verify a webhook

Pass the raw body, exactly as received, and the request headers. verify raises Didit::WebhookVerificationError for anything that is not a valid, fresh delivery, and returns a typed event otherwise.

require "didit"

WEBHOOK_SECRET = ENV.fetch("DIDIT_WEBHOOK_SECRET", "")

def handle_webhook(raw_body, headers)
  event = Didit::Webhooks.verify(raw_body, headers, WEBHOOK_SECRET)
  case event
  when Didit::Webhooks::StatusUpdatedEvent
    puts "#{event.session_id} #{event.status}"
  end
  200
rescue Didit::WebhookVerificationError => e
  puts "rejected: #{e.reason}"
  400
end

In Rails, call handle_webhook(request.raw_post, request.headers). While you rotate the secret, pass both: [new_secret, old_secret]. See Webhooks for the events and the signature scheme.

Screen a transaction

Submit a payment, withdrawal or crypto transfer to transaction monitoring; the response carries its status and risk score.

require "didit"

didit = Didit::Client.new

transaction = didit.transactions.create(
  transaction_id: "txn-1001",
  transaction_category: "finance",
  transaction_details: { direction: "outbound", amount: 1500, currency: "EUR" },
  subject: { entity_type: "individual", vendor_data: "user-123", full_name: "Maria Garcia" }
)
puts "#{transaction.status} #{transaction.score}"

Verify Authentication tokens

Didit::Authentication checks the access tokens your Authentication issuer signs, in your backend, without calling Didit for each request. It also exchanges codes, refreshes tokens, checks and revokes sessions, and runs step-ups.

Token verification makes the checks in Verify a token on your server, against your application’s issuer and signing keys.

require "didit"

# Your issuer URL, or Didit::Authentication.from_publishable_key("pk_live_...", client_id: ...).
AUTH = Didit::Authentication.new("https://your-app.auth.didit.me", client_id: "your-application-id")

def current_user(access_token)
  AUTH.verify_access_token(access_token).sub
rescue Didit::TokenVerificationError => e
  puts "rejected: #{e.reason}"
  nil
end

Errors

require "didit"

didit = Didit::Client.new

begin
  didit.sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
rescue Didit::NotFoundError
  puts "no such session"
rescue Didit::APIStatusError => e
  puts "#{e.status} #{e.request_id}"
end

Lists and files

require "didit"

didit = Didit::Client.new

# Lists page through every result.
didit.sessions.list(status: "Approved").auto_paging_each do |session|
  puts session.session_id
end

# Uploads take a Pathname, an IO or Didit::FilePart. A String is sent as the file's bytes.
result = didit.id_verification.verify(
  front_image: Pathname("id-front.jpg"),
  back_image: Pathname("id-back.jpg")
)
puts result.to_h

Server endpoint pages of the API reference have a Ruby sample for their operation, except for the endpoints and fields that no 1.0.1 release has yet, named in the overview.

Guides

Authentication

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Server SDKs

Integrations

Ruby SDK for KYC, AML and Transactions

Install

Configure the client

Create a session

Read the decision

Verify a webhook

Screen a transaction

Verify Authentication tokens

Errors

Lists and files

​Install

​Configure the client

​Create a session

​Read the decision

​Verify a webhook

​Screen a transaction

​Verify Authentication tokens

​Errors

​Lists and files

Install

Configure the client

Create a session

Read the decision

Verify a webhook

Screen a transaction

Verify Authentication tokens

Errors

Lists and files