> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

> Official Fyatu Java SDK — enterprise-grade card issuing and payment API client for Java applications.

> [!WARNING]
>
> This SDK is coming soon. Subscribe to our [changelog](https://docs.fyatu.com/v3/changelog/overview) to be notified when it's released.

The official Java SDK for FYATU API v3, compatible with Java 11+ and Android.

## Requirements

* Java 11 or higher
* Gradle or Maven

## Installation

### Gradle

```groovy theme={null}
dependencies {
    implementation 'com.fyatu:fyatu-java:1.0.0'
}
```

### Maven

```xml theme={null}
<dependency>
    <groupId>com.fyatu</groupId>
    <artifactId>fyatu-java</artifactId>
    <version>1.0.0</version>
</dependency>
```

## Quick Start

```java theme={null}
import com.fyatu.Fyatu;
import com.fyatu.model.Collection;
import com.fyatu.param.CreateCollectionParams;
import com.fyatu.param.CustomerParams;

public class Example {
    public static void main(String[] args) {
        Fyatu fyatu = Fyatu.builder()
            .appId("your_app_id")
            .secretKey("your_secret_key")
            .build();

        // Create a collection
        Collection collection = fyatu.collections().create(
            CreateCollectionParams.builder()
                .amount(10.00)
                .currency("USD")
                .reference("order_123")
                .description("Payment for Order #123")
                .customer(CustomerParams.builder()
                    .email("customer@example.com")
                    .name("Alice Example")
                    .build())
                .redirectUrl("https://yoursite.com/payment/success")
                .webhookUrl("https://yoursite.com/webhooks/fyatu")
                .build()
        );

        System.out.println(collection.getCheckoutUrl());
    }
}
```

## Spring Boot Integration

### Configuration

```yaml theme={null}
# application.yml
fyatu:
  app-id: ${FYATU_APP_ID}
  secret-key: ${FYATU_SECRET_KEY}
```

### Auto-Configuration

```java theme={null}
@Configuration
@EnableConfigurationProperties(FyatuProperties.class)
public class FyatuConfig {

    @Bean
    public Fyatu fyatu(FyatuProperties properties) {
        return Fyatu.builder()
            .appId(properties.getAppId())
            .secretKey(properties.getSecretKey())
            .build();
    }
}
```

### Service Usage

```java theme={null}
@Service
public class PaymentService {

    private final Fyatu fyatu;

    public PaymentService(Fyatu fyatu) {
        this.fyatu = fyatu;
    }

    public Collection createPayment(BigDecimal amount, String reference) {
        return fyatu.collections().create(
            CreateCollectionParams.builder()
                .amount(amount.doubleValue())
                .currency("USD")
                .reference(reference)
                .build()
        );
    }
}
```

## Features

* **Java 11+ Support** - Uses modern Java features
* **Builder Pattern** - Fluent API for all operations
* **Spring Boot Integration** - Auto-configuration support
* **Android Compatible** - Works with Android API 26+
* **Automatic Token Management** - Handles JWT refresh automatically
* **Thread-Safe** - Safe for concurrent use

## Configuration Options

```java theme={null}
Fyatu fyatu = Fyatu.builder()
    .appId("your_app_id")
    .secretKey("your_secret_key")

    // Optional configuration
    .baseUrl("https://api.fyatu.com/api/v3")
    .timeout(Duration.ofSeconds(30))
    .maxRetries(3)
    .httpClient(customHttpClient)
    .build();
```

## Available Services

| Service | Description |
| - | - |
| `fyatu.collections()` | Accept payments via checkout |
| `fyatu.refunds()` | Manage refunds |
| `fyatu.payouts()` | Send money to recipients |
| `fyatu.cardholders()` | Manage cardholders |
| `fyatu.cards()` | Issue and manage virtual cards |

\| `fyatu.account()` | Access account information |

## Error Handling

```java theme={null}
import com.fyatu.exception.*;

try {
    Payout payout = fyatu.payouts().create(
        CreatePayoutParams.builder()
            .amount(100.0)
            .currency("USD")
            .recipientId("invalid_id")
            .build()
    );
} catch (ValidationException e) {
    System.out.println("Validation failed: " + e.getDetails());
} catch (AuthenticationException e) {
    System.out.println("Authentication failed: " + e.getMessage());
} catch (InsufficientBalanceException e) {
    System.out.println("Insufficient balance: " + e.getMessage());
} catch (FyatuException e) {
    System.out.println("API error [" + e.getCode() + "]: " + e.getMessage());
}
```

## Webhook Verification

```java theme={null}
import com.fyatu.webhook.Webhook;
import com.fyatu.webhook.WebhookEvent;

// Spring Boot controller example
@RestController
public class WebhookController {

    @PostMapping("/webhooks/fyatu")
    public ResponseEntity<String> handleWebhook(
        @RequestBody String payload,
        @RequestHeader("X-Fyatu-Signature") String signature
    ) {
        boolean valid = Webhook.verifySignature(
            payload,
            signature,
            "your_webhook_secret"
        );

        if (!valid) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body("Invalid signature");
        }

        WebhookEvent event = Webhook.parseEvent(payload);
        System.out.println("Received event: " + event.getType());

        return ResponseEntity.ok("OK");
    }
}
```

## Async Support

```java theme={null}
import com.fyatu.FyatuAsync;
import java.util.concurrent.CompletableFuture;

FyatuAsync fyatuAsync = FyatuAsync.builder()
    .appId("your_app_id")
    .secretKey("your_secret_key")
    .build();

CompletableFuture<Collection> future = fyatuAsync.collections().create(
    CreateCollectionParams.builder()
        .amount(10.0)
        .currency("USD")
        .reference("order_123")
        .build()
);

future.thenAccept(collection -> {
    System.out.println("Created: " + collection.getId());
});
```

## Resources

* [API Reference](https://docs.fyatu.com/v3/api-reference/introduction)
* [Webhooks Guide](https://docs.fyatu.com/v3/concepts/webhooks)
* [GitHub Repository](https://github.com/fyatu/fyatu-java) *(Coming soon)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.