SDKs & Plugins

PayIsland provides official SDKs and plugins to help developers and merchants integrate faster. The SDKs wrap the PayIsland REST API, keep request and error handling consistent, and provide helpers for common payment workflows.

Base API URL:

https://ags.payislands.com

Sandbox and live mode are determined by the API key you use. There is no separate environment flag.

Available SDKs and Plugins

Platform	Package	Install command	Registry	GitHub
Node.js / TypeScript	@payisland/payisland-node	npm install @payisland/payisland-node		payisland-node
PHP	payisland/payisland-php	composer require payisland/payisland-php		payisland-php
Python	payisland	pip install payisland		payisland-python
Java	com.payislands:payisland-java	Add Maven dependency com.payislands:payisland-java:0.1.0		payisland-java
.NET	PayIsland	dotnet add package PayIsland		payisland-dotnet
Flutter / Dart	payisland	flutter pub add payisland		payisland-flutter
WooCommerce	PayIsland for WooCommerce	Install from GitHub ZIP	Not applicable	payisland-woocommerce

All SDKs currently support:

• Transaction initialization
• Transaction verification
• Webhook signature verification
• API error handling

Accept Your First Payment

1. Get your PayIsland secret key.
2. Create or identify your Payment Item ID.
3. Install the SDK for your language.
4. Initialize a transaction.
5. Redirect the customer to the returned authorization_url.
6. Verify the transaction after payment.
7. Fulfill only after successful verification or a confirmed webhook.

Initialize transaction:

POST /api/v1/transactions/in/initialize

Verify transaction:

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

Use this request shape when initializing a transaction:

{
  "callback_url": "https://example.com/webhooks/payislands",
  "payment_item_id": "6",
  "transaction_reference": "order_12345",
  "channel": "card",
  "amount": "1000",
  "customer_info": {
    "email": "ada@example.com",
    "phone_number": "08011112222",
    "first_name": "Ada",
    "last_name": "Lovelace"
  }
}

PayIsland expects amount in the major currency unit as a string. For example, "1000" means NGN 1,000. Do not multiply by 100.

Security

Secret keys must only be used in secure backend or server-side environments. Do not expose secret keys in frontend browser code or public mobile apps.

For frontend and mobile checkout flows, initialize the transaction from your backend, then pass the returned authorization_url to the frontend or mobile app. Always verify the transaction reference before fulfilling an order. Webhook signatures should be verified where configured.

Use placeholders such as PAYISLAND_SECRET_KEY, PAYISLAND_PAYMENT_ITEM_ID, and PAYISLAND_WEBHOOK_SECRET in code and deployment configuration. Do not commit real keys.

3DS and Pending Payments

For card transactions that require 3DS authentication, transaction verification may return pending until the customer completes the challenge or PayIsland receives the final callback or webhook. Do not fulfill orders on a pending status.

Transaction Verification

Use the transaction reference returned by PayIsland where available. Status values should be handled defensively:

Status	Recommended handling
paid, successful, success	Treat as successful. Fulfill the order if all other checks pass.
pending, unpaid	Treat as pending. Do not fulfill yet.
failed, cancelled, canceled, expired, reversed	Treat as failed or not completed. Do not fulfill.

Webhooks

Webhook events should not be trusted blindly. If a webhook secret is configured, verify the webhook signature using the raw request body before trusting the payload. Always call transaction verification before fulfilling.

Node.js / TypeScript

const hasValidSignature = payisland.webhooks.verifySignature({
  payload: rawBody,
  signature: req.headers["x-payisland-signature"] as string,
  secret: process.env.PAYISLAND_WEBHOOK_SECRET!,
});

if (!hasValidSignature) {
  throw new Error("Invalid PayIsland webhook signature");
}

const verification = await payisland.transactions.verify(webhook.reference);

PHP

$isValid = $payIsland->webhooks->verifySignature(
    $rawPayload,
    $signature,
    getenv('PAYISLAND_WEBHOOK_SECRET')
);

if (!$isValid) {
    throw new RuntimeException('Invalid PayIsland webhook signature');
}

$verification = $payIsland->transactions->verify($payload['reference']);

Python

is_valid = payisland.webhooks.verify_signature(
    payload=raw_payload,
    signature=signature,
    secret=os.environ["PAYISLAND_WEBHOOK_SECRET"],
)

if not is_valid:
    raise ValueError("Invalid PayIsland webhook signature")

verification = payisland.transactions.verify(webhook["reference"])

Java

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);

.NET

var isValid = payIsland.Webhooks.VerifySignature(
    rawPayload,
    signature,
    Environment.GetEnvironmentVariable("PAYISLAND_WEBHOOK_SECRET")!
);

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

var verification = await payIsland.Transactions.VerifyAsync(reference);

Flutter / Dart

final isValid = payIsland.webhooks.verifySignature(
  payload: rawPayload,
  signature: signature,
  secret: webhookSecret,
);

if (!isValid) {
  throw Exception('Invalid PayIsland webhook signature');
}

final verification = await payIsland.transactions.verify(reference);