The Straddle Ruby library provides convenient access to the Straddle REST API from any Ruby 3.2.0+ application. The library includes comprehensive support for all API endpoints with built-in error handling.

The SDK supports Ruby 3.2.0+ and provides a clean, idiomatic Ruby interface to the Straddle API.

​
Installation

Install the SDK by adding it to your application’s Gemfile:

gem "straddle"

Then run:

bundle install

For development environments, we recommend using dotenv to manage your API keys:

gem "dotenv", groups: [:development, :test]

​
Setup and Configuration

Require the SDK

Require the necessary gems in your Ruby application:

require "bundler/setup"
require "straddle"

Initialize the Client

Create a new instance of the Straddle client:

straddle = Straddle::Client.new(
  api_key: ENV["STRADDLE_API_KEY"], # This is the default and can be omitted
  environment: "sandbox" # or "production", defaults to "sandbox"
)

Never hardcode your API key directly in your code. Use environment variables or a secure configuration management system.

​
Implementation Examples

The Straddle Ruby SDK uses symbols for hash keys in method parameters. This follows Ruby conventions and provides better performance than string keys.

For account customers (non-platform), the flow is simpler as the account context is inferred from the API key:

require "bundler/setup"
require "straddle"

# Initialize the client
straddle = Straddle::Client.new(
  api_key: ENV["STRADDLE_API_KEY"],
  environment: "sandbox"
)

# 1. Create a customer
customer_response = straddle.customers.create(
  device: { ip_address: "192.168.0.1" },
  email: "customer@example.com",
  name: "Customer Name",
  phone: "+15555555555",
  type: "individual"
)
customer = customer_response.data

# 2. Link a bank account
paykey_response = straddle.bridge.link.bank_account(
  customer_id: customer.id,
  routing_number: "011000028",
  account_number: "000123456789",
  account_type: "checking"
)
paykey = paykey_response.data

# 3. Create a charge
charge = straddle.charges.create(
  amount: 100, # Amount in cents ($1.00)
  config: { balance_check: "required" },
  consent_type: "internet",
  currency: "USD",
  description: "Monthly subscription fee",
  device: { ip_address: "192.168.1.1" },
  external_id: "external_id",
  paykey: paykey.paykey,
  payment_date: "2025-01-30" # Can also use Date objects: Date.new(2025, 1, 30) # Can also use Date objects: Date.new(2025, 1, 30)
)
puts charge.data

​
Key Features

Idiomatic Ruby

Clean, Ruby-style interface following community conventions with snake_case methods and intuitive hash parameters.

Thread Safety

The client is thread-safe, allowing you to share a single instance across multiple threads in your application.

Automatic Retries

Built-in retry logic for transient errors with configurable retry strategies.

Error Handling

Comprehensive error classes that map to HTTP status codes for precise error handling.

​
Error Handling

The SDK provides specific exception types for different error cases:

​
SDK Requirements

Ruby Version

Ruby 3.2.0 or higher

Bundler

Bundler for dependency management

For more detailed information about the SDK structure and usage, refer to our API Documentation and GitHub repository.