Ruby SDK

The official Ruby SDK connects server applications to the Raims public API. It provides resource services, typed responses, cursor pagination, and webhook verification. Keep the API key in your backend, outside code distributed to customers and routine logs.

The SDK reference lists each resource's methods and parameters.

Install the SDK

Use Ruby 3.3 or later. The raims gem is available on RubyGems. Install it in your application's environment:

gem install raims

For Bundler, add the dependency to Gemfile, using RubyGems as the source:

source 'https://rubygems.org'
gem 'raims'

Install the dependencies:

bundle install

RubyGems and Bundler resolve the gem's declared dependencies. Keep your application's Gemfile.lock to preserve the selected versions. Load the SDK with require 'raims'.

Stable GitHub releases also provide raims.gem and SHA256SUMS. To install from a file, download both into a new directory through the release page or GitHub CLI:

gh release download --repo raimshq/raims-ruby --pattern raims.gem --pattern SHA256SUMS --dir raims-ruby-release

Check the download source and compare the SHA-256 of raims.gem with its entry in SHA256SUMS. Install the local file:

gem install ./raims-ruby-release/raims.gem

Configure the client

Obtain a credential through API keys and store it in RAIMS_API_KEY or your application's secret store. The key determines company, environment, and permissions. Sandbox and Production use https://api.raims.com.

require 'raims'

raims = Raims::RaimsClient.new(ENV.fetch('RAIMS_API_KEY'))
begin
  balance = raims.balances.retrieve
  request_id = balance.last_response.request_id
ensure
  raims.close
end

Reuse the client and close it when finished. RaimsClient.open with a block also guarantees closure. The following snippets assume an open raims instance. Timeouts use seconds; read retries are disabled by default.

Create a customer and a charge

Set customer_tax_id to the authorized customer's valid CPF or CNPJ. Create and persist separate customer_key and charge_key values for each intent before sending. due_date_unix is the charge's chosen due date in UTC Unix seconds; keep it when retrying the same intent.

customer = raims.customers.create(
  {tax_id: customer_tax_id},
  {idempotency_key: customer_key}
)

charge = raims.charges.create(
  {customer_id: customer.id, amount_cents: 15000,
   due_date: due_date_unix, title: 'Order 1234'},
  {idempotency_key: charge_key}
)

pending = charge.last_response.status_code == 202

15000 represents BRL 150.00. Inputs use hashes with JSON field names; omitted fields remain absent and nil sends JSON null where allowed. For example, raims.customers.update(customer.id, {external_reference: nil}) clears that reference; omission preserves its value. Responses expose readers such as customer.id; use key? to distinguish absence from null.

Pagination and pending results

page = raims.customers.list({page_size: 50})
page.auto_paging_each do |customer|
  process_customer(customer)
end

process_customer belongs to the application. each visits only the received page; auto_paging_each fetches subsequent pages and preserves filters and options. next_page and previous_page return another page or nil. Do not combine after and before or interpret cursor contents.

HTTP 202 indicates a pending result. Retrieve the resource or process the appropriate webhook before confirming a payment, refund, or cancellation.

Idempotency and errors

begin
  customer = raims.customers.retrieve(customer_id)
rescue Raims::RaimsError => error
  handle_failure(error.http_status, error.code, error.request_id)
end

handle_failure represents your failure handling. Use status, code, and Request-Id; human messages are not control codes. ArgumentError identifies invalid local arguments. Do not log credentials, complete bodies, or temporary access links.

The SDK does not generate idempotency keys or retry writes automatically. After a lost response, retrieve the resource and, when the endpoint permits retrying the request, reuse the original key and parameters. Configure max_network_retries on the client or request options for eligible GET/HEAD read retries only. The default is zero; Retry-After follows the SDK's bounded wait policy. See Idempotency.

Use Sandbox

Use a Sandbox key and a charge belonging to that environment:

Raims::RaimsClient.open(ENV.fetch('RAIMS_SANDBOX_API_KEY')) do |sandbox|
  result = sandbox.simulations.charges.confirm_payment(sandbox_charge_id)
end

The SDK does not turn a Production key into Sandbox or offer an environment selector. See the conditions under Simulations. Email requests and webhook deliveries may reach external destinations even in Sandbox; use authorized destinations.

Receive webhooks

Preserve raw_body, the string containing the original bytes received by your server, and signing_headers, the hash containing webhook-id, webhook-timestamp, and webhook-signature. Preserve repeated occurrences so ambiguity can be rejected.

begin
  event = Raims::Webhook.construct_event(
    raw_body, signing_headers, ENV.fetch('RAIMS_WEBHOOK_SECRET')
  )
  persist_event(event)
rescue Raims::SignatureVerificationError
  reject_delivery
end

persist_event and reject_delivery belong to your application. RAIMS_WEBHOOK_SECRET contains the webhook's secret_key, not the API key. Do not reserialize JSON before verification. Do not process an invalid event.

The default tolerance is 300 seconds; keep the server clock synchronized. A valid signature does not prevent redelivery: check type and environment, deduplicate the event id, and store the work durably before returning success. webhook-id identifies the delivery. See Receive events.

Update the SDK

For applications using Bundler, update the gem and its dependencies within the constraints declared in Gemfile:

bundle update raims

Review and keep the updated Gemfile.lock. For an installation managed directly through RubyGems, use:

gem update raims

If Gemfile used source downloaded from GitHub, replace its path: or git: declaration with gem 'raims', using https://rubygems.org as the source, and run bundle update raims. The require 'raims' statement stays the same.

Read the version history and test the flows used by your integration before updating the application. Installation does not enable automatic future updates.