Quickstart

This walkthrough creates a customer, attaches a payment instrument, and charges them — the full happy path you'll repeat across every Easy Labs integration.

1. Get your API keys

Generate an API key in the Easy Labs dashboard. Use a sk_test_… key for development (routes to the sandbox automatically) and a sk_live_… key in production. Treat the key as a secret: load it from the environment, never commit it.

export EASY_API_KEY="sk_test_..."

2. Initialize the SDK

require "easy_sdk"

client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))

The constructor immediately calls GET /validate-key to verify the key. A bad key raises EasyLabs::AuthenticationError here — not on your first real request.

3. Make your first call

customer = client.customers.create(
  first_name: "Ada",
  last_name:  "Lovelace",
  email:      "ada@example.com"
)

puts customer[:id] # => "cust_..."

Every response is a plain Ruby Hash with symbol keys. There is no wrapper object, no .attributes accessor — what you get back is what the API returned.

4. Handle the response

begin
  charge = client.transfers.create(
    amount:   1500,            # cents
    currency: "USD",
    source:   payment_instrument_id
  )

  puts "Charged #{charge[:amount]} #{charge[:currency]}"
rescue EasyLabs::InvalidRequestError => e
  # 400 / 422 — bad input. e.code holds the machine-readable code.
  warn "Bad request: #{e.code}: #{e.message}"
rescue EasyLabs::RateLimitError => e
  # 429 — back off using the Retry-After header.
  sleep(e.retry_after_seconds || 1)
  retry
rescue EasyLabs::Error => e
  # All other failures (auth, conflict, server, network).
  warn "API failure (#{e.status}): #{e.message}"
end

See Error handling for the full class hierarchy.

What's next

Authentication — sandbox vs. live, key rotation, multi-tenant.
Resources › Customers — full customer-resource reference.
Resources › Subscriptions — recurring billing.
Webhooks — verify and react to async events.