Java SDK

Java SDK

Official Java SDK for the Islamic Open Finance™ API.

::: caution Preview Release The Java SDK is in preview and under active development. The API may change before the stable 1.0 release. Subscribe to our GitHub Discussions for release announcements. :::

Installation

Maven

<dependency>
    <groupId>com.islamicopenfinance</groupId>
    <artifactId>iof-java</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'com.islamicopenfinance:iof-java:1.0.0'

Quick Start

import com.islamicopenfinance.IOFClient;
import com.islamicopenfinance.model.Contract;
import com.islamicopenfinance.param.ContractCreateParams;

public class Example {
    public static void main(String[] args) {
        IOFClient client = IOFClient.builder()
            .apiKey("iof_sk_live_...")
            .build();

        ContractCreateParams params = ContractCreateParams.builder()
            .type("MURABAHA")
            .counterparty(
                ContractCreateParams.Counterparty.builder()
                    .id("cpty_123")
                    .build()
            )
            .terms(
                ContractCreateParams.Terms.builder()
                    .amount(50000L)
                    .currency("USD")
                    .build()
            )
            .build();

        Contract contract = client.contracts().create(params);
        System.out.println("Created contract: " + contract.getId());
    }
}

Configuration

IOFClient client = IOFClient.builder()
    .apiKey("iof_sk_live_...")
    .baseUrl("https://api.islamicopenfinance.com")
    .timeout(Duration.ofSeconds(30))
    .build();

Working with Contracts

Create

Contract contract = client.contracts().create(params);

Retrieve

Contract contract = client.contracts().retrieve("contract_123");

List

ContractListParams listParams = ContractListParams.builder()
    .status("active")
    .limit(20L)
    .build();

ContractCollection contracts = client.contracts().list(listParams);

for (Contract contract : contracts.getData()) {
    System.out.println(contract.getId());
}

Error Handling

try {
    Contract contract = client.contracts().create(params);
} catch (IOFException e) {
    System.err.println("IOF error: " + e.getMessage());
    System.err.println("Code: " + e.getCode());

    if ("VALIDATION_ERROR".equals(e.getCode())) {
        for (IOFException.Detail detail : e.getDetails()) {
            System.err.println(detail.getField() + ": " + detail.getMessage());
        }
    }
} catch (IOFNetworkException e) {
    System.err.println("Network error: " + e.getMessage());
}

Async Operations

CompletableFuture<Contract> future = client.contracts().createAsync(params);

future.thenAccept(contract -> {
    System.out.println("Created: " + contract.getId());
}).exceptionally(e -> {
    System.err.println("Error: " + e.getMessage());
    return null;
});

Webhooks

import com.islamicopenfinance.webhook.Webhook;
import com.islamicopenfinance.model.Event;

@PostMapping("/webhooks")
public ResponseEntity<String> handleWebhook(
    @RequestBody String payload,
    @RequestHeader("X-IOF-Signature") String signature
) {
    try {
        Event event = Webhook.constructEvent(
            payload,
            signature,
            System.getenv("WEBHOOK_SECRET")
        );

        if ("contract.created".equals(event.getType())) {
            Contract contract = (Contract) event.getData().getObject();
            // Handle contract created
        }

        return ResponseEntity.ok("OK");
    } catch (SignatureVerificationException e) {
        return ResponseEntity.status(401).body("Invalid signature");
    }
}

Requirements

• Java 11+

Next Steps

• Error Handling - Error patterns
• Pagination - List operations
• API Reference - All endpoints