Raims Elixir

Official Elixir SDK for the Raims public API.

Use resource modules, response models, cursor pagination, structured errors, and webhook signature verification in server applications. Requires Elixir 1.18 or later with Erlang/OTP 27 or later.

Install with Hex

Check the current dependency configuration for raims on Hex:

If Hex is not installed, run mix local.hex first.

mix hex.info raims

Copy the dependency shown on the Config: line into deps/0 in your application's mix.exs, then fetch and compile it:

mix deps.get
mix compile

Keep the application's mix.lock under version control. To update within your dependency requirement, run mix deps.update raims, compile, and run your application's checks. Review the current Hex configuration when you want to adopt a release outside that requirement. Installing the SDK does not apply future updates automatically.

Source code and release archives remain available on GitHub. See installation and updates for Git and local path dependencies, migration to Hex, and the raims.tar release artifact.

First request

client = Raims.Client.new(System.fetch_env!("RAIMS_API_KEY"))

case Raims.Customers.list(client, %{page_size: 20}) do
  {:ok, response} ->
    Enum.each(response.data["list"], fn customer ->
      MyApp.process_customer(customer["id"])
    end)

  {:error, error} ->
    MyApp.handle_raims_error(error.kind, error.request_id)
end

MyApp 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.

Create a charge

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.

{:ok, response} =
  Raims.Charges.create(
    client,
    %{
      customer_id: customer_id,
      amount_cents: 15000,
      due_date: due_date,
      title: "Order 1234"
    },
    idempotency_key: order_idempotency_key
  )

charge_id = response.data["id"]
request_id = response.request_id

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

Pagination

{:ok, first_page} = Raims.Customers.list(client, %{page_size: 50})

first_page
|> Raims.Page.stream()
|> Enum.each(fn customer -> MyApp.process_customer(customer["id"]) end)

The stream fetches further pages as needed and preserves filters and request options. Raims.Page.next_page/1 and previous_page/1 provide explicit navigation. Use Raims.Page.to_list/2 to collect a bounded number of items.

Resource modules

Resource modules expose functions such as create, retrieve, update, delete, and list according to the public contract. Every operation has a ! variant that raises Raims.Error on an API or transport failure. See the method reference.

Documentation

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

Distributed under the MIT license.