Docs
Checking Raims account
Integrations

Java SDK

Install the official Java SDK and connect your backend to the Raims public API.

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.

For a minimal console project, choose one build file. In an existing application, merge the dependency and keep its current build configuration.

pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>raims-read</artifactId>
  <version>1.0-SNAPSHOT</version>
  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.raims</groupId>
      <artifactId>raims-java</artifactId>
      <version>SDK_VERSION</version>
    </dependency>
  </dependencies>
</project>

Configure the client

  1. Prepare the credential

    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.

    For this first read, use a Sandbox key with View customers permission. The request only reads one page; it does not create customers or request emails.

  2. Save the read example

    The class has no package declaration; save it at the path below. The installation build configurations let you run it with Maven or Gradle.

    src/main/java/ReadCustomers.java
    Java
    import com.raims.RaimsClient;
    import com.raims.exception.ApiException;
    import com.raims.exception.ConnectionException;
    import com.raims.param.ListCustomersParams;
    
    public final class ReadCustomers {
        public static void main(String[] args) {
            String apiKey = System.getenv("RAIMS_API_KEY");
            if (apiKey == null || apiKey.isBlank()) {
                throw new IllegalStateException("Set RAIMS_API_KEY on the server.");
            }
            try (RaimsClient raims = RaimsClient.builder()
                    .setApiKey(apiKey)
                    .setMaxNetworkRetries(0)
                    .build()) {
                var customers = raims.customers().list(
                    ListCustomersParams.builder().setPageSize(10).build());
                System.out.printf("HTTP status: %d; items: %d%n",
                    customers.getLastResponse().getStatusCode(), customers.getList().size());
            } catch (ApiException error) {
                System.err.printf("HTTP status: %s; code: %s; Request-Id: %s%n",
                    error.getStatusCode(), error.getCode(), error.getRequestId());
                System.exit(1);
            } catch (ConnectionException error) {
                System.err.println("Read failed before a conclusive response. Check the connection.");
                System.exit(1);
            }
        }
    }
  3. Run and check the result

    From the project directory, with RAIMS_API_KEY available to the process, run:

    Shell
    mvn compile exec:java -Dexec.mainClass=ReadCustomers

    With Gradle, run gradle run.

    A successful read prints HTTP status: 200 and the number of items in this page. items: 0 is a valid empty result for the key’s company and environment. It is not an authentication failure.

What to check

The SDK reads the list and page envelope below. In an empty page, has_next: false means there is no next page. A nonempty page also returns customer records; the program prints only their count.

HTTP 200 response example excerptGET /v1/customers

No customers found

JSON
{
  "list": [],
  "page": {
    "page_size": 10,
    "has_next": false,
    "has_previous": false,
    "next_after": null,
    "previous_before": null
  }
}

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

This is a backend snippet, after loading the order from your application’s storage. Keep the customer key separate from the charge key. Save the entire request payload, including the amount and title, before sending; read it again on retries instead of generating new values.

Input from the saved orderSource and purpose
customerTaxIdCustomer tax ID already authorized and saved by your application.
customerIdempotencyKeyIdempotency key for creating this customer; saved before the first request.
chargeIdempotencyKeyA different idempotency key for this charge; saved with the order.
chargeDueDateChosen due date, saved in UTC Unix seconds.
Java
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("Pedido 1234")
        .build(),
    RequestOptions.builder().setIdempotencyKey(chargeIdempotencyKey).build());

String chargeId = charge.getId();
int httpStatus = charge.getLastResponse().getStatusCode();
String requestId = charge.getLastResponse().getRequestId();
boolean pending = httpStatus == 202;

Persist the returned customer ID and charge ID on the order before returning success to your caller. The charge ID is the value used to resume the read below; the SDK variables are not durable storage.

ResultWhat to do next
HTTP 201The charge was created. Save its ID; creation does not confirm payment. This snippet does not request email or payment issuance.
HTTP 202 in a creation that requests payment issuanceSave the same returned ID and keep the order pending. Retrieve that charge; do not create another one to resolve the pending result.
Error or missing responseHandle the structured error. If execution is uncertain, keep the intent and reconcile before retrying with the original key and payload.

The canonical creation example below shows only the ID and status fields:

HTTP 201 response example excerptPOST /v1/charges

Charge without a link or email request

JSON
{
  "id": "ch_1Q2W3E4R5T6Y7U8I9O0P",
  "status": 0
}

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.

The following backend snippet counts at most 100 customers across pages, without logging their records. Keep the configured client open during iteration.

Java
int visited = 0;
var page = raims.customers().list(
    ListCustomersParams.builder().setPageSize(50).build());
for (var customer : page.autoPagingIterable()) {
    visited++;
    if (visited == 100) break;
}
System.out.printf("Items visited: %d%n", visited);

Items visited: 0 means the query found no customers. 100 means the chosen limit was reached; it does not prove there are no more records. A page error interrupts the count. Save progress only after processing a complete page if your job must resume later.

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

HTTP 202 keeps the result pending. It does not confirm payment and the SDK does not start polling. When resuming the saved order, load chargeId from storage and retrieve that same charge once:

Java
var current = raims.charges().retrieve(chargeId);
System.out.printf("HTTP status: %d; charge status: %d%n",
    current.getLastResponse().getStatusCode(), current.getStatus());

HTTP 200 here confirms that the read succeeded. Interpret the returned status and payment_information using the charge reference; a successful GET does not mean the charge was paid or that issuance completed. If issuance is still pending, keep the same ID. Repeated reads do not speed up processing or issue another payment; contact support if the condition persists.

Idempotency and errors

Failures use exceptions in com.raims.exception. With the client and imports from the first example, read the API error's code and field details:

Java
try {
    raims.customers().list(ListCustomersParams.builder().setPageSize(10).build());
} catch (ApiException error) {
    System.err.printf("HTTP status: %s; code: %s; Request-Id: %s%n",
        error.getStatusCode(), error.getCode(), error.getRequestId());
    var details = error.getDetails();
    if (details != null) {
        for (var item : details) {
            var detail = item.getAsJsonObject();
            System.err.printf("field: %s; code: %s%n",
                detail.get("field").getAsString(), detail.get("code").getAsString());
        }
    }
}

getCode() returns error.code, and getApiMessage() returns the API's diagnostic text. getMessage() is the exception's generic message. Use the code and HTTP status to control the integration, not either message.

getDetails() returns a defensive copy of the JsonArray, or null when details are absent or are not an array. Changes to that copy do not change the exception. 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.

Do not log complete responses, credentials, personal documents, or temporary URLs. See Idempotency and the SDK error guide.

For example, if the read above returns HTTP 403 with API_KEY_PERMISSION_DENIED, the key lacks access to list customers. Enable View customers on the appropriate key and retry the read. Repeating it with the same permissions will not resolve that error.

Read field and code from each detail's JsonObject, as shown above. Check HTTP response codes for other failures.

For an uncertain write, recover the saved key and the entire original payload. If the charge ID was received, retrieve that ID first. Within the idempotency retention period, a compatible retry can return the preserved result, including a pending 202. A key with different parameters can be rejected; do not change the due date or create a new key to bypass the uncertainty. After retention expires, reconcile before another write.

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.

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