Skip to main content

Java SDK

Official package:

Maven Central

  • Maven coordinates: com.payislands:payisland-java:0.1.0
  • Registry: Maven Central
  • GitHub: payisland-java

Installation​

<dependency>
  <groupId>com.payislands</groupId>
  <artifactId>payisland-java</artifactId>
  <version>0.1.0</version>
</dependency>

Initialize a Transaction​

import com.payislands.PayIsland;

import java.util.Map;

PayIsland payIsland = new PayIsland(System.getenv("PAYISLAND_SECRET_KEY"));

Map<String, Object> response = payIsland.transactions().initialize(Map.of(
    "callback_url", "https://example.com/webhooks/payislands",
    "payment_item_id", "6",
    "transaction_reference", "order_" + System.currentTimeMillis(),
    "channel", "card",
    "amount", "1000",
    "customer_info", Map.of(
        "email", "ada@example.com",
        "phone_number", "08011112222",
        "first_name", "Ada",
        "last_name", "Lovelace"
    )
));

System.out.println(response);

Redirect the customer to the returned data.authorization_url to complete payment.

Verify a Transaction​

Map<String, Object> verification = payIsland.transactions().verify("order_12345");
Map<String, Object> data = (Map<String, Object>) verification.get("data");
String status = (String) data.get("payment_status");

if (java.util.List.of("paid", "successful", "success").contains(status)) {
    // Fulfill the order.
} else if (java.util.List.of("pending", "unpaid").contains(status)) {
    // Wait for completion and verify again later.
} else {
    // Treat as failed or not completed.
}

The SDK calls:

GET /api/v1/transactions/in/check-transaction-status/{reference}

Webhook Signature Verification​

boolean isValid = payIsland.webhooks().verifySignature(
    rawPayload,
    signature,
    System.getenv("PAYISLAND_WEBHOOK_SECRET")
);

if (!isValid) {
    throw new SecurityException("Invalid PayIsland webhook signature");
}

Map<String, Object> verification = payIsland.transactions().verify(reference);

Verify the transaction reference before fulfilling, even after a valid webhook signature.

Notes​

  • Use PAYISLAND_SECRET_KEY only on the server.
  • PayIsland chooses sandbox or live mode from the API key.
  • The default API base URL is https://ags.payislands.com.
  • Amounts are strings in the major currency unit. "1000" means NGN 1,000.