Inttegro Java SDK

The official Java client for building server-side Inttegro integrations.

API documentation · Integration guides

Fastest, most modern path: connect an agent to Inttegro MCP at https://mcp.inttegro.com, then ask it to run design_integration. It will produce an implementation and test plan for your application. Use this SDK when you are ready to connect that plan to your Java service.

All official Inttegro SDKs expose the same API capabilities. This package adds Java-specific builders, domain types, and HTTP integration.

Install

Requires Java 17 or newer.

<dependency>
  <groupId>com.inttegro</groupId>
  <artifactId>inttegro-sdk-java</artifactId>
  <version>6.0.0</version>
</dependency>

Store your secret key in the server environment:

export INTTEGRO_API_KEY="your_secret_key"

Never put the key in browser code, a mobile app, or source control. The client uses https://api.inttegro.com by default.

Create a hosted checkout

Create and finalize an order, then send the customer to its hosted invoice URL:

import com.inttegro.ApiException;
import com.inttegro.Client;
import com.inttegro.RequestMeta;
import com.inttegro.money.Currency;
import com.inttegro.customers.CustomerData;
import com.inttegro.orders.CheckoutSettings;
import com.inttegro.orders.Order;
import com.inttegro.orders.OrderCreateParams;
import com.inttegro.orders.OrderLineItemParams;
import com.inttegro.prices.PriceParams;
import com.inttegro.products.ProductType;

public class CheckoutExample {
  public static void main(String[] args) throws Exception {
    Client inttegro = new Client(System.getenv("INTTEGRO_API_KEY"));

    try {
      Order order = inttegro.orders().create(OrderCreateParams.builder()
          .requestMeta(RequestMeta.withIdempotencyKey("checkout-cart-123"))
          .customerData(CustomerData.builder()
              .name("Akua Mensah")
              .email("akua@example.com")
              .phoneNumber("+233544998605")
              .build())
          .finalizeOrder(true)
          .checkoutSettings(CheckoutSettings.builder()
              .redirectUrl("https://example.com/orders/complete")
              .cancelUrl("https://example.com/cart")
              .build())
          .lineItem(OrderLineItemParams.product(product -> product
              .type(ProductType.DIGITAL)
              .name("Monthly subscription")
              .quantity(1)
              .price(PriceParams.of(Currency.GHS, 5000))))
          .build());

      if (order.invoice == null || order.invoice.format == null || order.invoice.format.web == null) {
        throw new IllegalStateException("Order did not include a checkout URL");
      }
      System.out.println(order.id + " " + order.invoice.format.web.url);
    } catch (ApiException error) {
      System.err.println(error.getCode() + ": " + error.getDetail());
      throw error;
    }
  }
}

Amounts use integer minor units: 5000 GHS is GHS 50.00. Reuse the same idempotency key when retrying the same logical write. If you omit one, the SDK generates a UUIDv7 key for mutating calls.

Create a partial refund

Refunds target paid order line items and return money to the original payment method:

import com.inttegro.money.AmountParams;
import com.inttegro.money.Currency;
import com.inttegro.refunds.CreateRefundLineItem;
import com.inttegro.refunds.CreateRefundParams;
import com.inttegro.refunds.RefundReason;

var refund = inttegro.refunds().create(CreateRefundParams.builder()
    .orderId("or_0123456789abcdefghijklmnopqrstuvwxyzABCD")
    .reason(RefundReason.ITEM_RETURNED)
    .lineItem(CreateRefundLineItem.builder()
        .orderLineItemId("oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN")
        .refundAmount(AmountParams.of(Currency.GHS, 2500))
        .build())
    .build());

System.out.println(refund.id + " " + refund.status);

Use refunds().create, refunds().cancel, refunds().lookup, and refunds().page to manage the refund lifecycle.

Observe SDK operations

The SDK emits vendor-neutral OpenTelemetry spans through your application's provider. It never configures an exporter or sends telemetry by itself. Java's global provider is used automatically, or inject the OpenTelemetry instance owned by your application:

Client inttegro = new Client(
    System.getenv("INTTEGRO_API_KEY"),
    "https://api.inttegro.com",
    httpClient,
    openTelemetry
);

Spans are named after logical operations such as inttegro.orders.create. HTTP attempts, response receipt, and decoding are span events. API keys, bodies, resource IDs, dynamic URLs, and exception messages are never recorded. See SDK observability for the complete contract. The five-argument constructor can disable SDK telemetry when needed.

Report SDK failures

Provide an application-owned reporter to receive one immutable, typed, privacy-safe report after an SDK operation finally fails. The default UNEXPECTED policy reports transport, decoding, SDK, unknown_error, and server-side failures while leaving normal 4xx API errors alone:

import com.inttegro.Client;
import com.inttegro.diagnostics.ErrorReport;

Client inttegro = new Client(
    System.getenv("INTTEGRO_API_KEY"),
    (ErrorReport report) -> errorCollector.enqueue(report)
);

Pass ErrorReportingPolicy.ALL to the three-argument constructor to include expected API failures; interrupted requests are never reported. Reports contain the logical operation, static route, server host, status and request IDs when available, duration, safe API error codes, SDK identity, stable fingerprint, exception type, and trace IDs when tracing is active. They exclude credentials, headers, bodies, resource IDs, dynamic URLs, exception messages, and stack traces. Reporter failures are isolated and the original SDK exception is still thrown.

Error reporting is completely opt-in. Without an ErrorReporter, the SDK does not calculate report metadata, create an event ID or timestamp, allocate a report, or serialize a payload.

Work with the API

The SDK covers orders and checkout, customers, products and prices, purchase intents, payment methods, balances, payouts and refunds, notifications, files, application settings, keys, and country specifications. Resource clients use camel-case fields such as purchaseIntents and paymentMethods.

Java-specific features:

• Typed request and domain types with fluent builders for common resources.
• Domain packages mirror the API vocabulary: notification types live in com.inttegro.chimes, payment lifecycle types in com.inttegro.payments, and payment-method types in com.inttegro.paymentmethods.
• Native enums live beside the domain types that use them.
• JDK HttpClient transport with Jackson response mapping.
• An injectable HttpClient and base URL for connection pools, proxies, tests, and timeouts.
• A constructed client is safe to share across threads.
• Structured ApiException fields for status, code, detail, cause, and recovery guidance.

See the API reference for request fields and lifecycle rules, errors for recovery guidance, and idempotency for safe retries.

Verify a release

The GitHub release for each version is the canonical record. It contains the exact signed JAR, source JAR, Javadoc JAR, POM, and Maven Central publication bundle, plus SHA-256 checksums and a Sigstore attestation tied to the source commit and release workflow.

sha256sum --check SHA256SUMS
gh attestation verify inttegro-sdk-java-5.1.0.jar \
  --repo inttegro/inttegro-sdk-java

Develop

mvn test