Raims Ruby

Official Ruby SDK for the Raims public API.

Use resource services, read-only response objects, cursor pagination, structured errors, and webhook signature verification in server applications. Requires Ruby 3.3 or later.

Install the raims gem from RubyGems:

gem install raims

For a Bundler application, add the gem to your Gemfile:

source 'https://rubygems.org'

gem 'raims'

Then run:

bundle install

Load the SDK with require 'raims'. Keep your application's Gemfile.lock under version control to retain its resolved dependency versions.

The GitHub releases also provide raims.gem and SHA256SUMS. See installation and updates for verified GitHub downloads and updating an existing installation.

require 'raims'

Raims::RaimsClient.open(ENV.fetch('RAIMS_API_KEY')) do |raims|
  customers = raims.customers.list({page_size: 20})
  customers.each do |customer|
    process_customer(customer.id)
  end
end

process_customer represents your application's processing. The base URL is https://api.raims.com for both Sandbox and Production. The key determines the company, environment, and permissions. Keep it on the server, outside source control and logs.

Define and persist customer_id, due_date, and order_idempotency_key for the order before sending the request. Amounts use integer cents: 15000 represents BRL 150.00. The due date uses UTC Unix seconds.

raims = Raims::RaimsClient.new(ENV.fetch('RAIMS_API_KEY'))

begin
  charge = raims.charges.create(
    {customer_id: customer_id, amount_cents: 15000, due_date: due_date,
     title: 'Order 1234'},
    {idempotency_key: order_idempotency_key}
  )
  request_id = charge.last_response.request_id
ensure
  raims.close
end

The SDK does not generate idempotency keys or retry writes automatically. After losing a response, keep the same key and parameters and follow the endpoint's recovery rules. HTTP 202 means processing is pending; retrieve the resource to follow the result.

Raims::RaimsClient.open(ENV.fetch('RAIMS_API_KEY')) do |raims|
  raims.customers.list({page_size: 50}).auto_paging_each do |customer|
    process_customer(customer.id)
  end
end

each reads only the current page. auto_paging_each fetches further pages as needed and preserves filters and request options. next_page and previous_page provide explicit navigation. Use auto_paging_to_a(limit) to collect a bounded number of items.

Services expose methods such as create, retrieve, update, delete, and list according to the public contract. See the method reference.

• Installation and updates
• Configuration, responses, and documents
• Pagination
• Errors, idempotency, and retries
• Receiving webhooks
• Contributing and security
• Public API

Distributed under the MIT license.