Ruby SDK for Straddle

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.

Straddle Account Customers
Embed Customers

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: "[email protected]",
  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

This example demonstrates the complete flow for Embed customers:

require "bundler/setup"
require "straddle"

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

# 1. Create an organization
org_response = straddle.embed.organizations.create(
  name: "SDK Test Organization in Sandbox"
)
organization = org_response.data

# 2. Create an account for the organization
account_response = straddle.embed.accounts.create(
  organization_id: organization.id,
  account_type: "business",
  business_profile: {
    name: "SDK Test",
    website: "straddle.com"
  },
  access_level: "standard"
)
account = account_response.data

# 3. Create a customer
customer_response = straddle.customers.create(
  straddle_account_id: account.id,
  device: { ip_address: "192.168.0.1" },
  email: "[email protected]",
  name: "Customer Name",
  phone: "+15555555555",
  type: "individual"
)
customer = customer_response.data

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

# 5. Create a charge
charge = straddle.charges.create(
  straddle_account_id: account.id,
  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"
)
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:

Common Error Types

begin
  charge = straddle.charges.create(
    amount: 1000,
    currency: "USD",
    # ... other required params
  )
rescue Straddle::Errors::BadRequestError => e
  puts "Bad request: #{e.message}"
  puts "Status: #{e.status_code}"
  puts "Response body: #{e.response_body}" if e.respond_to?(:response_body)
rescue Straddle::Errors::UnprocessableEntityError => e
  puts "Validation error: #{e.message}"
  puts "Errors: #{e.errors}" if e.respond_to?(:errors)
rescue Straddle::Errors::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Straddle::Errors::PermissionDeniedError => e
  puts "Permission denied: #{e.message}"
rescue Straddle::Errors::NotFoundError => e
  puts "Resource not found: #{e.message}"
rescue Straddle::Errors::RateLimitError => e
  puts "Rate limit exceeded: #{e.message}"
  puts "Retry after: #{e.retry_after}" if e.respond_to?(:retry_after)
rescue Straddle::Errors::InternalServerError => e
  puts "Server error: #{e.message}"
rescue Straddle::Errors::APIError => e
  # Catch all other API errors
  puts "API error: #{e.message}"
end

Common error types include:

BadRequestError (400)
UnprocessableEntityError (422)
AuthenticationError (401)
PermissionDeniedError (403)
NotFoundError (404)
RateLimitError (429)
InternalServerError (>=500)

Timeout Configuration

Configure request timeouts:

# Configure timeout in seconds
straddle = Straddle::Client.new(
  api_key: ENV["STRADDLE_API_KEY"],
  timeout: 30 # 30 seconds
)

# Or configure with more granular settings
straddle = Straddle::Client.new(
  api_key: ENV["STRADDLE_API_KEY"],
  timeout: {
    connect: 5,
    read: 30,
    write: 10
  }
)

Retry Configuration

Configure automatic retries:

straddle = Straddle::Client.new(
  api_key: ENV["STRADDLE_API_KEY"],
  max_retries: 3,
  retry_delay: 1.0 # seconds
)

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.

Fundamentals

SDKs

Customers

Bridge

Paykeys

Charges

Payouts

Funding

Payments

Embed

Installation

Setup and Configuration

Implementation Examples

Key Features

Idiomatic Ruby

Thread Safety

Automatic Retries

Error Handling

Error Handling

SDK Requirements

Ruby Version

Bundler

​Installation

​Setup and Configuration

​Implementation Examples

​Key Features

Idiomatic Ruby

Thread Safety

Automatic Retries

Error Handling

​Error Handling

​SDK Requirements

Ruby Version

Bundler

Installation

Setup and Configuration

Implementation Examples

Key Features

Error Handling

SDK Requirements