Python SDK

Use the raims package in your integration backend, with synchronous and asynchronous clients, typed parameters, read-only responses, cursor pagination, and webhook authentication.

Install the package

The SDK requires Python 3.10 or later. In your application's virtual environment:

python -m pip install raims

The raims package is on PyPI and keeps the same import name. Pip resolves its dependencies. Check the release history and pin the version you choose in your application's requirements.txt or lockfile.

GitHub releases also provide wheel and source archives. To install the wheel, download the .whl file and SHA256SUMS into a raims-python-release directory, keep its original filename, and verify the hash. In a Bash shell, with only that wheel in the directory:

python -m pip install ./raims-python-release/raims-*.whl

In PowerShell, select the downloaded file:

$wheels = @([System.IO.Directory]::GetFiles((Resolve-Path ./raims-python-release).Path, '*.whl'))
if ($wheels.Count -ne 1) { throw 'Keep exactly one downloaded wheel in this directory.' }
python -m pip install $wheels[0]

Configure the client

Get a key from API keys and store it in a vault or protected application environment variable. Keep the credential in the backend, out of browsers, applications distributed to customers, and logs.

The validated API key determines company, environment, and permissions. Sandbox and Production use https://api.raims.com.

import os

from raims import RaimsClient

api_key = os.environ["RAIMS_API_KEY"]
with RaimsClient(api_key, max_network_retries=0) as raims:
    customers = raims.customers.list({"page_size": 20})
    for customer in customers:
        print(customer.id)

Reuse the client for its intended lifecycle. with closes the synchronous client; for asynchronous use, choose AsyncRaimsClient with async with and await on calls. Keep one asynchronous instance per event loop lifecycle.

Create a customer and a charge

customer_tax_id is the valid CPF or CNPJ of the authorized customer. customer_idempotency_key and charge_idempotency_key are separate keys created and persisted before the requests. charge_due_date is the chosen, persisted due date in UTC Unix seconds.

from raims import RequestOptions

with RaimsClient(api_key) as raims:
    customer = raims.customers.create(
        {"tax_id": customer_tax_id},
        options=RequestOptions(idempotency_key=customer_idempotency_key),
    )
    charge = raims.charges.create(
        {
            "customer_id": customer.id,
            "amount_cents": 15000,
            "due_date": charge_due_date,
            "title": "Order 1234",
        },
        options=RequestOptions(idempotency_key=charge_idempotency_key),
    )
    response = charge.last_response
    if response is not None:
        print(response.status_code, response.request_id)

If the CPF or CNPJ already exists in the same company and environment, the customer is updated and keeps its identifier. 15000 represents BRL 150.00. Keep the key and every parameter, including the due date, when recovering the same intent after losing a response. See Create a charge.

Inputs retain the API JSON names. Omitting a key leaves the field absent; None sends null. Check the contract before clearing a value. Responses preserve future fields and should not be changed directly.

Pagination and pending results

list() fetches one page. Normal iteration reads only the received items; next_page() and previous_page() preserve filters. auto_paging_iter() loads subsequent pages as you consume it. With the asynchronous client, use await for the query and async for for the iterator. process_customer represents your application logic.

with RaimsClient(api_key) as raims:
    page = raims.customers.list({"page_size": 50})
    for customer in page.auto_paging_iter():
        process_customer(customer.id)

Copy the received cursors and keep the filters; do not send after and before together. See Listing and pagination.

An HTTP 202 response indicates a pending result. It does not confirm payment or financial completion and does not start automatic polling. Retrieve the resource or follow the appropriate event before confirming the effect in your application.

Idempotency and errors

Handle HTTP failures through ApiError, using status_code, code, and request_id. ConnectionError indicates a transport failure and can leave a write inconclusive. max_network_retries configures retries for reads only; the default is zero.

The SDK sends an idempotency key only when your application supplies it to an endpoint that accepts Idempotency-Key. It does not generate keys or retry writes automatically. A timeout does not prove that a write was rejected.

Make decisions using the HTTP status and structured code; error.message is a human diagnostic that can change. Do not log complete responses, credentials, personal documents, or temporary URLs. See Idempotency and the SDK error guide.

Use Sandbox

Use a Sandbox key for simulations in raims.simulations.charges and raims.simulations.refunds. A Production key does not become a Sandbox key when these services are used. Check the conditions in the Simulations reference.

Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for the integration.

Receive webhooks

raw_body contains the received bytes and received_headers contains webhook-id, webhook-timestamp, and webhook-signature. reject_delivery and persist_event represent your application logic. Do not process a delivery whose signature failed.

from raims import SignatureVerificationError, Webhook

try:
    event = Webhook.construct_event(raw_body, received_headers, webhook_secret)
except SignatureVerificationError:
    reject_delivery()
else:
    persist_event(event)

Use the secret_key returned when creating or rotating the webhook, which differs from the API Bearer key. Read the body before the JSON parser and preserve its bytes: do not reserialize the content before authentication.

After authentication, check the type and environment, deduplicate by the event id, and store the work durably before responding with success. The webhook-id header identifies the delivery, not the event. See Receive events.

Update the SDK

To install the current stable version, run in your application environment:

python -m pip install --upgrade raims

Review the release notes and test the flows used by your integration. Pin the version and dependencies in your application's dependency configuration to reproduce the installation. Future updates are not installed automatically.

If you installed from GitHub, the raims import stays the same. Update the dependency source in your application configuration if it pins a Git URL or local file. To keep using the GitHub wheel, download the files from the new release, verify the hash, and install the new wheel with --upgrade.

The SDK version is independent of the API HTTP version /v1. Full guides and the method reference are in the SDK repository.