PayIsland Flutter/Dart SDK

Official Flutter/Dart SDK for integrating with PayIsland payment APIs.

This is the Phase 1 foundation for server-side or trusted Dart integrations. It supports client initialization, inbound transaction initialization, transaction verification, webhook signature verification, typed API exceptions, examples, and tests.

Installation

flutter pub add payisland

Or add it manually:

dependencies:
  payisland: ^0.1.0

Then run:

dart pub get

Initialization

import 'package:payisland/payisland.dart';

final payIsland = PayIslandClient(secretKey: 'test_secret_key');

PayIsland determines sandbox or live mode from the API key. The SDK does not expose a sandbox/live environment flag.

Transaction Initialization

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

print(response['data']['authorization_url']);

For card transactions, 3DS authentication can leave a transaction in a pending or intermediate state until the customer completes authentication and PayIsland finalizes the result. Always verify the transaction reference before fulfillment.

Transaction Verification

final response = await payIsland.transactions.verify('order_123');

print(response);

Webhook Verification

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

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

Webhook signatures are verified with HMAC SHA256 using constant-time comparison where possible. After verifying the signature, verify the transaction reference with PayIsland before fulfilling an order.

Error Handling

API errors throw PayIslandApiException:

try {
  final response = await payIsland.transactions.verify('order_123');
  print(response);
} on PayIslandApiException catch (error) {
  print(error.message);
  print(error.statusCode);
  print(error.responseBody);
}

Configuration

Use PayIslandConfig when you need to override the base URL or timeout, usually for tests:

final payIsland = PayIslandClient.fromConfig(
  PayIslandConfig(
    secretKey: 'test_secret_key',
    baseUrl: 'https://ags.payislands.com',
    timeout: Duration(seconds: 30),
  ),
);

Default base URL:

https://ags.payislands.com

Authentication uses:

Authorization: Bearer <secretKey>

Default headers:

Content-Type: application/json
Accept: application/json
User-Agent: payisland-flutter

Examples

dart run example/initialize_payment.dart
dart run example/verify_payment.dart <reference>
dart run example/webhook_verification.dart

Environment variables:

PAYISLAND_SECRET_KEY=your_test_secret_key
PAYISLAND_PAYMENT_ITEM_ID=your_payment_item_id
PAYISLAND_WEBHOOK_SECRET=your_webhook_secret

Development Commands

dart pub get
dart analyze
dart test
dart format .
dart pub publish --dry-run

Pub.dev Publishing

Before publishing, run:

dart format .
dart analyze
dart test
dart pub publish --dry-run

Publish when the dry run is clean:

dart pub publish

License

MIT. See LICENSE.