Skip to main content

Node.js / TypeScript SDK

Official package:

npm

Installation​

npm install @payisland/payisland-node

Initialize a Transaction​

import { PayIsland } from "@payisland/payisland-node";

const payisland = new PayIsland({
  secretKey: process.env.PAYISLAND_SECRET_KEY!
});

const response = await payisland.transactions.initialize({
  callback_url: "https://example.com/webhooks/payislands",
  payment_item_id: "6",
  transaction_reference: `order_${Date.now()}`,
  channel: "card",
  amount: "1000",
  customer_info: {
    email: "ada@example.com",
    phone_number: "08011112222",
    first_name: "Ada",
    last_name: "Lovelace"
  }
});

console.log(response.data.authorization_url);

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

Verify a Transaction​

const verification = await payisland.transactions.verify("order_12345");
const status = verification.data.payment_status;

if (["paid", "successful", "success"].includes(status)) {
  // Fulfill the order.
} else if (["pending", "unpaid"].includes(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​

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

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

const verification = await payisland.transactions.verify(webhook.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.