Elixir SDK

The official Elixir SDK connects server applications to the Raims public API. Use resource modules, response models, pagination, and webhook verification. Keep the API key in your backend, outside applications distributed to customers and routine logs.

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

Install the SDK

Use Elixir 1.18 or later with Erlang/OTP 27 or later. The official raims package is available on Hex.

If Hex is not installed yet, install it once:

mix local.hex

From your project directory, check the current stable version and configuration:

mix hex.info raims

Copy the Config: line into the list returned by deps/0 in your application's mix.exs. Then fetch the dependencies and compile:

mix deps.get
mix compile

Mix resolves dependencies according to the configuration and records their versions in mix.lock. Keep that file for repeatable installation.

GitHub releases continue to provide source code and the distribution archive. For a Git or local path installation, read the repository instructions.

Configure the client

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

client =
  Raims.Client.new(System.fetch_env!("RAIMS_API_KEY"),
    timeout: 30_000,
    max_network_retries: 0
  )

{:ok, balance} = Raims.Balances.retrieve(client)
request_id = balance.request_id

Timeouts use milliseconds. The client is immutable and reusable; it does not own a process that needs stopping. Each HTTP attempt closes its connection when finished. The following examples use this client.

Create a customer and a charge

customer_tax_id contains the authorized customer's valid CPF or CNPJ. customer_key and charge_key are separate keys, persisted before requests. Also persist due_date_unix, the due date in UTC Unix seconds.

with {:ok, customer} <-
       Raims.Customers.create(client, %{tax_id: customer_tax_id},
         idempotency_key: customer_key
       ),
     {:ok, charge} <-
       Raims.Charges.create(
         client,
         %{
           customer_id: customer.data["id"],
           amount_cents: 15000,
           due_date: due_date_unix,
           title: "Order 1234"
         },
         idempotency_key: charge_key
       ) do
  {:ok, charge.data["id"], charge.status_code}
else
  {:error, error} -> {:error, error.kind, error.request_id}
end

15000 represents BRL 150.00. Maps accept atom or string keys with JSON names. Omission keeps a field absent; nil sends null where allowed. During an update, %{external_reference: nil} can clear the reference; omission preserves it. Responses use response.data; Access.fetch/2 distinguishes an absent field from one containing nil.

Pagination and pending results

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

first_page
|> Raims.Page.stream()
|> Stream.map(fn customer -> customer["id"] end)
|> Enum.take(100)

A response list contains only the received page. Raims.Page.stream/1 fetches further pages on demand; Enum.take/2 bounds collection. The stream raises Raims.Error if a page fails. next_page/1 and previous_page/1 return {:ok, response}, {:ok, nil}, or {:error, error}, preserving filters and options. Do not send after and before together.

HTTP 202 accepts work with a pending result. Retrieve the resource or follow the appropriate event before confirming its financial effect.

Idempotency and errors

case Raims.Customers.retrieve(client, customer_id) do
  {:ok, response} -> MyApp.process_customer(response.data)
  {:error, error} ->
    MyApp.handle_failure(error.kind, error.status_code, error.code, error.request_id)
end

MyApp represents your business handling. Functions return {:ok, response} or {:error, %Raims.Error{}} tuples; ! variants raise the exception. Invalid local arguments raise ArgumentError. Use category, status, code, and Request-Id without logging bodies or credentials.

The SDK does not generate idempotency keys or retry writes. After a lost response, retrieve the operation; when retrying is permitted, use the same key and parameters. max_network_retries enables eligible GET/HEAD read retries only, with a default of zero. Waits, Retry-After, and attempts share the timeout budget. See Idempotency.

Use Sandbox

Use a Sandbox key and a resource from that environment:

sandbox = Raims.Client.new(System.fetch_env!("RAIMS_SANDBOX_API_KEY"))
{:ok, result} = Raims.Simulations.Charges.confirm_payment(sandbox, sandbox_charge_id)

The SDK does not select or change a credential's environment. Financial simulations accept Sandbox only; a Production key remains Production on a local host. See Simulations. Email requests and webhooks may reach external destinations even in Sandbox; use authorized destinations only.

Receive webhooks

Use the original raw_body binary and a list of received header pairs containing webhook-id, webhook-timestamp, and webhook-signature. The list preserves duplicates so the verifier can reject ambiguity.

case Raims.Webhook.construct_event(raw_body, signing_headers, webhook_secret) do
  {:ok, event} -> MyApp.persist_event(event)
  {:error, error} -> MyApp.reject_delivery(error)
end

webhook_secret is the webhook's secret_key held in your secret store; the MyApp handlers belong to your application. Do not parse and rebuild JSON before verifying its signature. The default tolerance is 300 seconds, with a synchronized clock. verify_signature/4 verifies without decoding JSON.

After verification, check type and environment, deduplicate the event id, and store the work durably before returning success. A valid signature does not prevent redelivery; webhook-id identifies the delivery. See Receive events.

Update the SDK

Check the current stable version and configuration:

mix hex.info raims

If needed, adjust the declaration in deps/0 using the Config: line shown by Hex. Then update the SDK within the declared constraints:

mix deps.update raims
mix compile

If the dependency used github:, git:, or path:, replace that declaration with the current Hex configuration and run the same commands. Also remove Git-only options such as ref:, branch:, and tag:. The Raims modules stay the same.

Review and keep the updated mix.lock. Read the release notes and test the flows used by your integration before updating the application. Installation does not apply future updates automatically.