Ruby SDK

Official Zentra library for Ruby applications

The Zentra Ruby SDK provides convenient access to the Zentra API from Ruby applications.

The reviewed public HTTP surface for this SDK is transfers, webhooks, virtual accounts, payments, cards, and tenant-enabled identity. Customers, wallets, and other generated helpers may still exist for compatibility or draft use cases, but they are not the default reviewed public API path.

Bundler

gem 'zentra'

Configuration

Initialize the client with your API key:

require 'zentra'

Zentra.configure do |config|
  config.api_key = ENV['ZENTRA_SECRET_KEY']
  config.environment = :sandbox # or :live
end

client = Zentra::Client.new

Resources

The SDK maps to reviewed API resources as follows:

• client.payments: Payment processing
• client.transfers: Bank transfers
• client.virtual_accounts: Virtual bank accounts
• client.cards: Card issuing
• client.identity: KYC verification
• client.webhooks: Webhook handling

Examples

Create a Transfer

begin
  transfer = client.transfers.create(
    amount_minor: 500000,
    account_number: '0123456789',
    bank_code: '058',
    account_name: 'Vendor Settlement Account',
    narration: 'Vendor payout',
    reference: 'TRF_12345'
  )
  puts "Queued transfer: #{transfer.reference}"
rescue Zentra::Error => e
  puts "Error: #{e.message}"
end

Create Charge

charge = client.payments.charge(
  amount_minor: 500000, # ₦5,000.00
  currency: 'NGN',
  email: '[e-mail]',
  reference: 'ORD_12345',
  capture_mode: 'customer_action_required'
)

verified = client.payments.verify(charge['reference'])
puts "Status: #{verified['status']}"

Verify Webhook Signature

# Sinatra example
post '/webhooks' do
  payload = request.body.read
  signature = request.env['HTTP_X_ZENTRA_SIGNATURE']

  if client.webhooks.verify(payload, signature)
    # Process webhook
    status 200
    'Verified'
  else
    status 400
    'Invalid signature'
  end
end

Error Handling

The SDK raises typed exceptions for API errors:

begin
  client.payments.verify('INVALID_REF')
rescue Zentra::InvalidRequestError => e
  puts "Bad request: #{e.message}"
rescue Zentra::AuthenticationError
  puts 'Check your API key'
rescue Zentra::APIError => e
  puts "API error: #{e.message}"
end

Rails Integration

For Rails applications, configure in an initializer:

# config/initializers/zentra.rb
Zentra.configure do |config|
  config.api_key = Rails.application.credentials.zentra[:api_key]
  config.environment = Rails.env.production? ? :live : :sandbox
end

Source Code

GitHub Repo

View source code

RubyGems

Download gem