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

# Ruby SDK

> Official Fyatu Ruby SDK — card issuing and payments for Ruby and Rails applications.

<Warning>
  This SDK is coming soon. Subscribe to our [changelog](/v3/changelog/overview) to be notified when it's released.
</Warning>

The official Ruby SDK for FYATU API v3, designed for Ruby on Rails and other Ruby frameworks.

## Requirements

* Ruby 3.0 or higher

## Installation

Add to your Gemfile:

```ruby theme={null}
gem 'fyatu'
```

Then run:

```bash theme={null}
bundle install
```

Or install directly:

```bash theme={null}
gem install fyatu
```

## Quick Start

```ruby theme={null}
require 'fyatu'

Fyatu.configure do |config|
  config.app_id = 'your_app_id'
  config.secret_key = 'your_secret_key'
end

# Create a collection
collection = Fyatu::Collection.create(
  amount: 10.00,
  currency: 'USD',
  reference: 'order_123',
  description: 'Payment for Order #123',
  customer: {
    email: 'customer@example.com',
    name: 'Alice Example'
  },
  redirect_url: 'https://yoursite.com/payment/success',
  webhook_url: 'https://yoursite.com/webhooks/fyatu'
)

puts collection.checkout_url
```

## Rails Integration

### Configuration

Create `config/initializers/fyatu.rb`:

```ruby theme={null}
Fyatu.configure do |config|
  config.app_id = Rails.application.credentials.fyatu[:app_id]
  config.secret_key = Rails.application.credentials.fyatu[:secret_key]
end
```

### Generator

```bash theme={null}
rails generate fyatu:install
```

This creates the initializer and a sample webhook controller.

## Features

* **Ruby 3.0+ Support** - Modern Ruby with keyword arguments
* **Rails Integration** - First-class Rails support with generators
* **ActiveModel-like Objects** - Familiar API response handling
* **Automatic Token Management** - Handles JWT refresh automatically
* **Thread-Safe** - Safe for concurrent use with Puma/Sidekiq

## Configuration Options

```ruby theme={null}
Fyatu.configure do |config|
  config.app_id = 'your_app_id'
  config.secret_key = 'your_secret_key'

  # Optional configuration
  config.base_url = 'https://api.fyatu.com/api/v3'
  config.timeout = 30
  config.max_retries = 3
end
```

## Available Resources

| Resource            | Description                    |
| ------------------- | ------------------------------ |
| `Fyatu::Collection` | Accept payments via checkout   |
| `Fyatu::Refund`     | Manage refunds                 |
| `Fyatu::Payout`     | Send money to recipients       |
| `Fyatu::Cardholder` | Manage cardholders             |
| `Fyatu::Card`       | Issue and manage virtual cards |

\| `Fyatu::Account` | Access account information |

## Error Handling

```ruby theme={null}
begin
  payout = Fyatu::Payout.create(
    amount: 100,
    currency: 'USD',
    recipient_id: 'invalid_id'
  )
rescue Fyatu::ValidationError => e
  puts "Validation failed: #{e.details}"
rescue Fyatu::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Fyatu::InsufficientBalanceError => e
  puts "Insufficient balance: #{e.message}"
rescue Fyatu::Error => e
  puts "API error [#{e.code}]: #{e.message}"
end
```

## Webhook Verification

```ruby theme={null}
# Rails controller example
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def fyatu
    signature = request.headers['X-Fyatu-Signature']
    payload = request.raw_post

    unless Fyatu::Webhook.verify_signature(payload, signature, ENV['FYATU_WEBHOOK_SECRET'])
      render plain: 'Invalid signature', status: :unauthorized
      return
    end

    event = JSON.parse(payload)

    case event['type']
    when 'collection.completed'
      handle_collection_completed(event['data'])
    when 'payout.completed'
      handle_payout_completed(event['data'])
    end

    render plain: 'OK', status: :ok
  end

  private

  def handle_collection_completed(data)
    # Process completed collection
  end

  def handle_payout_completed(data)
    # Process completed payout
  end
end
```

## Pagination

```ruby theme={null}
# List all collections with pagination
Fyatu::Collection.list(limit: 10).each do |collection|
  puts "Collection: #{collection.id} - #{collection.status}"
end

# Or with auto-pagination
Fyatu::Collection.auto_paging_each(limit: 100) do |collection|
  puts "Collection: #{collection.id}"
end
```

## Resources

* [API Reference](/v3/api-reference/introduction)
* [Webhooks Guide](/v3/concepts/webhooks)
* [GitHub Repository](https://github.com/fyatu/fyatu-ruby) *(Coming soon)*