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
:
Then run:
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: "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
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
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.io"
},
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: "customer@example.com" ,
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:
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)
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
}
)
Configure automatic retries:
straddle = Straddle :: Client . new (
api_key: ENV [ "STRADDLE_API_KEY" ],
max_retries: 3 ,
retry_delay: 1.0 # seconds
)
SDK Requirements
Bundler Bundler for dependency management
For more detailed information about the SDK structure and usage, refer to our API Documentation and GitHub repository .