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.
<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>plugins {
id 'application'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.raims:raims-java:SDK_VERSION'
}
application {
mainClass = 'ReadCustomers'
}plugins {
application
}
repositories {
mavenCentral()
}
dependencies {
implementation("com.raims:raims-java:SDK_VERSION")
}
application {
mainClass.set("ReadCustomers")
}Maven and Gradle resolve the SDK and its transitive dependencies through Maven Central. For a manual installation, download the JAR, POM, and SHA256SUMS to the same directory and verify the hashes. Sources and Javadoc are also available.
From that directory, install the JAR with its POM into your local Maven repository:
mvn install:install-file -Dfile=raims-java.jar -DpomFile=raims-java.pomConfigure the client
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.
Save the read example
The class has no
packagedeclaration; save it at the path below. The installation build configurations let you run it with Maven or Gradle.src/main/java/ReadCustomers.java Javaimport 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); } } }Run and check the result
From the project directory, with
RAIMS_API_KEYavailable to the process, run:Shellmvn compile exec:java -Dexec.mainClass=ReadCustomersWith Gradle, run
gradle run.A successful read prints
HTTP status: 200and the number of items in this page.items: 0is 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.
No customers found
{
"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 order | Source and purpose |
|---|---|
customerTaxId | Customer tax ID already authorized and saved by your application. |
customerIdempotencyKey | Idempotency key for creating this customer; saved before the first request. |
chargeIdempotencyKey | A different idempotency key for this charge; saved with the order. |
chargeDueDate | Chosen due date, saved 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("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.
| Result | What to do next |
|---|---|
HTTP 201 | The 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 issuance | Save 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 response | Handle 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:
Charge without a link or email request
{
"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.
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:
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:
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.
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.