Node.js SDK

Use the @raimshq/raims package in your Node.js backend. The SDK includes ESM and CommonJS modules, TypeScript declarations, resource services, cursor pagination, and webhook authentication.

Install the package

The SDK requires Node.js 22 or later and includes ESM and CommonJS modules and TypeScript types. From your application directory:

npm install @raimshq/raims

The @raimshq/raims package includes the runtime and type declarations. Keep your application's lockfile to reproduce the installed versions.

GitHub releases also provide raims-node.tgz and SHA256SUMS. To install the archive, download both to a raims-node-release directory, verify the hash, and run:

npm install ./raims-node-release/raims-node.tgz

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 Raims from '@raimshq/raims';

const apiKey = process.env.RAIMS_API_KEY;
if (!apiKey) throw new Error('Set RAIMS_API_KEY on the server.');

const raims = new Raims(apiKey, { maxNetworkRetries: 0 });
const customers = await raims.customers.list({ page_size: 20 });
for (const customer of customers.list) {
  console.log(customer.id);
}

Reuse the instance to reuse HTTP connections. In CommonJS, import it with const Raims = require('@raimshq/raims'). The following snippets assume an application-configured raims instance.

Create a customer and a charge

customerTaxId is the valid CPF or CNPJ of the authorized customer. customerIdempotencyKey and chargeIdempotencyKey are separate keys created and persisted before the requests. chargeDueDate is the chosen, persisted due date in UTC Unix seconds.

const customer = await raims.customers.create(
  {
    tax_id: customerTaxId,
  },
  { idempotencyKey: customerIdempotencyKey },
);

const charge = await raims.charges.create(
  {
    customer_id: customer.id,
    amount_cents: 15000,
    due_date: chargeDueDate,
    title: 'Order 1234',
  },
  { idempotencyKey: chargeIdempotencyKey },
);

const { statusCode, requestId } = charge.lastResponse;

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.

undefined omits a property; null is sent as null. Check the contract before clearing a field. Integers must fit within Number.MAX_SAFE_INTEGER, without conversion through fractional numbers.

Pagination and pending results

await list() fetches one page in list; nextPage() and previousPage() preserve filters and return null when there is no continuation. for await loads subsequent pages as you consume them; leaving the loop prevents further fetches. processCustomer represents your application logic.

for await (const customer of raims.customers.list({ page_size: 50 })) {
  await processCustomer(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

HTTP errors expose statusCode, code, and requestId. ConnectionError indicates a transport failure and can leave a write inconclusive. maxNetworkRetries configures retries for GET 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

rawBody contains the original bytes, such as a Buffer or Uint8Array. receivedHeaders contains the received headers. persistEvent and rejectDelivery represent your application logic; a persistence failure must return an HTTP error to allow redelivery.

import { SignatureVerificationError, Webhook } from '@raimshq/raims';

try {
  const event = Webhook.constructEvent(rawBody, receivedHeaders, webhookSecret);
  await persistEvent(event);
} catch (error) {
  if (error instanceof SignatureVerificationError) rejectDelivery();
  else throw error;
}

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 from your application directory:

npm install @raimshq/raims@latest

Review the release notes and test the flows used by your integration. Future updates are not installed automatically. If you use the TGZ, download the files from the current stable release again, verify the hash, and install the new archive.

When migrating from an earlier TGZ, replace the raims dependency with @raimshq/raims and update your imports and require calls.

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