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

# Java SDK

> Installation, initialization, and usage guide for the Waffo Java SDK.

## Requirements

* Java 8 or later (supports 8, 11, 17, 21)
* Maven 3.6+ or Gradle 6.0+

## Installation

**Maven**

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

**Gradle**

```groovy theme={null}
implementation 'com.waffo:waffo-java:3.1.0'
```

> [!NOTE]
>
> Please check the latest version on [Maven Central](https://central.sonatype.com/artifact/com.waffo/waffo-java).

## Initialization

```java theme={null}
import com.waffo.Waffo;
import com.waffo.types.config.WaffoConfig;
import com.waffo.types.config.Environment;

WaffoConfig config = WaffoConfig.builder()
    .apiKey("your-api-key")
    .privateKey("your-base64-encoded-private-key")
    .waffoPublicKey("waffo-public-key")  // Get this from Waffo
    .merchantId("your-merchant-id")      // Automatically injected into all requests
    .environment(Environment.SANDBOX)    // SANDBOX or PRODUCTION
    .build();

Waffo waffo = new Waffo(config);
```

## Payments

```java theme={null}
import com.waffo.types.ApiResponse;
import com.waffo.types.order.*;
import com.waffo.types.payment.ProductName;
import com.waffo.types.iso.CurrencyCode;
import java.util.UUID;

String paymentRequestId = UUID.randomUUID().toString().replace("-", "");

CreateOrderParams params = CreateOrderParams.builder()
    .paymentRequestId(paymentRequestId)
    .merchantOrderId("ORDER_" + System.currentTimeMillis())
    .orderCurrency(CurrencyCode.HKD)
    .orderAmount("100.00")
    .orderDescription("Premium Plan")
    .notifyUrl("https://your-site.com/webhook/waffo")
    .successRedirectUrl("https://your-site.com/payment/success")
    .failedRedirectUrl("https://your-site.com/payment/failed")
    .cancelRedirectUrl("https://your-site.com/payment/cancel")
    .userInfo(UserInfo.builder()
        .userId("user_123")
        .userEmail("user@example.com")
        .userTerminal(UserTerminalType.WEB)
        .build())
    .goodsInfo(GoodsInfo.builder()
        .goodsName("Premium Plan")
        .goodsUrl("https://your-site.com/product/001")
        .build())
    .paymentInfo(PaymentInfo.builder()
        .productName(ProductName.ONE_TIME_PAYMENT)
        .build())
    .build();

ApiResponse<CreateOrderData> response = waffo.order().create(params);
if (response.isSuccess()) {
    CreateOrderData data = response.getData().get();
    System.out.println("Redirect URL: " + data.fetchRedirectUrl());
}
```

## Error handling

```java theme={null}
import com.waffo.exception.WaffoUnknownStatusException;
import com.waffo.exception.WaffoException;

try {
    ApiResponse<CreateOrderData> response = waffo.order().create(params);
} catch (WaffoUnknownStatusException e) {
    // Important: The payment may have succeeded! Please use the query API to confirm
} catch (WaffoException e) {
    // Client-side errors (configuration, signature, etc.)
}
```

## Package registry

* [Maven Central](https://central.sonatype.com/artifact/com.waffo/waffo-java)


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