Java SDK

Use com.raims:raims-java to connect your Java backend to the public API. The SDK provides resource services, typed builders and responses, cursor pagination, and webhook authentication.

Install the package

The SDK requires Java 11 or later and is available on Maven Central as com.raims:raims-java. Find the current stable version at that link and replace SDK_VERSION in the examples below with that version. Keep your selected version in the application's configuration.

Maven

Add the dependency to pom.xml:

<dependency>
  <groupId>com.raims</groupId>
  <artifactId>raims-java</artifactId>
  <version>SDK_VERSION</version>
</dependency>

Gradle

In build.gradle, use the Maven Central repository and declare the dependency:

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.raims:raims-java:SDK_VERSION'
}

For Kotlin DSL, in build.gradle.kts:

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.raims:raims-java:SDK_VERSION")
}

Maven and Gradle resolve the SDK and its transitive dependencies through Maven Central. GitHub releases also provide the JAR, POM, sources, Javadoc, and SHA256SUMS. To use those files, see installation from GitHub.

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 com.raims.RaimsClient;
import com.raims.param.ListCustomersParams;

try (RaimsClient raims = RaimsClient.builder()
        .setApiKey(System.getenv("RAIMS_API_KEY"))
        .setMaxNetworkRetries(0)
        .build()) {
    var customers = raims.customers().list(
        ListCustomersParams.builder().setPageSize(20).build());
    customers.getList().forEach(customer -> System.out.println(customer.getId()));
}

Reuse a RaimsClient instance across calls and threads. The client implements AutoCloseable; use try-with-resources for a short scope or call close() when shutting down a shared client. The following snippets assume an application-managed raims instance that remains open.

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 a long containing the chosen, persisted due date in UTC Unix seconds.

import com.raims.RequestOptions;
import com.raims.param.CreateCustomerParams;
import com.raims.param.CreateChargeParams;

var customer = raims.customers().create(
    CreateCustomerParams.builder().setTaxId(customerTaxId).build(),
    RequestOptions.builder().setIdempotencyKey(customerIdempotencyKey).build());

var charge = raims.charges().create(
    CreateChargeParams.builder()
        .setCustomerId(customer.getId())
        .setAmountCents(15000)
        .setDueDate(chargeDueDate)
        .setTitle("Order 1234")
        .build(),
    RequestOptions.builder().setIdempotencyKey(chargeIdempotencyKey).build());

int httpStatus = charge.getLastResponse().getStatusCode();
String requestId = charge.getLastResponse().getRequestId();

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.

Omitting a setter keeps the field absent. Setters ending in Null send null for fields that allow it. Check the contract before clearing a value.

Pagination and pending results

list() fetches a typed page with getList(). nextPage() and previousPage() preserve filters and return null when there is no continuation. autoPagingIterable() advances as you consume it; keep the client open during iteration. processCustomer represents your application logic.

for (var customer : raims.customers().list().autoPagingIterable()) {
    processCustomer(customer.getId());
}

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

Failures use exceptions in com.raims.exception. Use getStatusCode(), getCode(), and getRequestId() to handle HTTP errors. A connection failure can leave a write inconclusive. setMaxNetworkRetries configures read retries; 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

rawBodyBytes contains the received bytes. receivedDeliveryId, receivedTimestamp, and receivedSignature are the header values read by your server. Reject the delivery if constructEvent throws a signature verification exception.

import com.raims.WebhookUtility;
import com.google.gson.JsonObject;
import java.util.Map;

Map<String, String> headers = Map.of(
    "webhook-id", receivedDeliveryId,
    "webhook-timestamp", receivedTimestamp,
    "webhook-signature", receivedSignature);

JsonObject event = WebhookUtility.constructEvent(rawBodyBytes, headers, webhookSecret);

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

Find the current stable version of com.raims:raims-java on Maven Central, update the dependency version in pom.xml, build.gradle, or build.gradle.kts, and run your integration tests.

If your application installed the JAR from GitHub, the com.raims:raims-java coordinates stay the same. Use the version available on Maven Central in your application dependency.

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