Java SDK

Official Java SDK for the Islamic Open Finance™ API.

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,
            "whsec_..."
        );

        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