> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usezentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash Bundler theme={null}
  gem 'zentra'
  ```

  ```bash gem theme={null}
  gem install zentra
  ```
</CodeGroup>

## Configuration

Initialize the client with your API key:

```ruby theme={null}
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

```ruby theme={null}
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

```ruby theme={null}
charge = client.payments.charge(
  amount_minor: 500000, # ₦5,000.00
  currency: 'NGN',
  email: 'user@example.com',
  reference: 'ORD_12345',
  capture_mode: 'customer_action_required'
)

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

### Verify Webhook Signature

```ruby theme={null}
# 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:

```ruby theme={null}
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:

```ruby theme={null}
# 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

<CardGroup cols={2}>
  <Card title="GitHub Repo" icon="github" href="https://github.com/zentra/zentra-ruby">
    View source code
  </Card>

  <Card title="RubyGems" icon="gem" href="https://rubygems.org/gems/zentra">
    Download gem
  </Card>
</CardGroup>