Skip to main content

PayIsland for WooCommerce

PayIsland for WooCommerce allows WooCommerce merchants to accept PayIsland payments without writing code.

  • GitHub: payisland-woocommerce
  • Checkout flow: PayIsland hosted checkout redirect
  • Supported checkout types: modern WooCommerce Checkout Block and classic [woocommerce_checkout] shortcode checkout

Overview​

The plugin redirects customers from WooCommerce to PayIsland hosted checkout. It does not collect card details inside WooCommerce, which reduces PCI and security exposure for merchants.

The plugin supports:

  • Modern WooCommerce Checkout Block
  • Classic [woocommerce_checkout] shortcode checkout
  • PayIsland hosted checkout redirect
  • Callback verification
  • Webhook handling
  • Admin configuration for secret key, payment item ID, payment channel, and logging

Requirements​

  • WordPress
  • WooCommerce
  • PHP >= 7.4
  • PayIsland secret key
  • PayIsland payment item ID

Installation​

  1. Download the plugin ZIP from GitHub.
  2. In WordPress admin, go to Plugins > Add New > Upload Plugin.
  3. Upload the ZIP file.
  4. Install and activate PayIsland for WooCommerce.
  5. Confirm WooCommerce is installed and active.

Configuration​

  1. Install and activate the plugin.
  2. Go to WooCommerce > Settings > Payments.
  3. Enable PayIsland.
  4. Add Secret Key.
  5. Add Payment Item ID.
  6. Select Payment Channel.
  7. Add Webhook/Callback URL.
  8. Enable debug logging during testing.
  9. Save changes.

Sandbox and live mode are determined by the PayIsland API key. The plugin does not have a separate environment flag.

Payment Flow​

  1. The customer selects PayIsland at checkout.
  2. The plugin initializes a PayIsland transaction with POST /api/v1/transactions/in/initialize.
  3. PayIsland returns an authorization URL.
  4. The customer is redirected to PayIsland hosted checkout.
  5. PayIsland sends the customer back to the callback URL after payment.
  6. PayIsland can also send a webhook event to the configured webhook URL.
  7. The plugin verifies the transaction using GET /api/v1/transactions/in/check-transaction-status/{reference} before updating the WooCommerce order.

PayIsland expects amounts in the major currency unit. For example, "7000" means NGN 7,000. Do not multiply by 100.

Checkout Blocks Support​

The plugin supports the modern WooCommerce Checkout Block. If PayIsland does not appear in block checkout, confirm the plugin is active, PayIsland is enabled under WooCommerce payments, and the required settings are saved.

Classic Checkout Support​

The plugin also supports the classic checkout page rendered with:

[woocommerce_checkout]

If PayIsland does not appear in Checkout Blocks during testing, try a classic checkout page to isolate whether the issue is checkout block configuration or gateway configuration.

Callback URL / Webhook URL​

The callback and webhook URLs must be public HTTPS URLs. For local testing, callback_url cannot be localhost. Use a public HTTPS tunnel such as ngrok.

Configure the callback or webhook URL in WooCommerce > Settings > Payments > PayIsland. The plugin verifies callbacks and webhooks before fulfilling an order.

If a webhook secret is configured, the plugin verifies webhook signatures. Leave the webhook secret empty until PayIsland provides one for your account.

Troubleshooting​

PayIsland Not Visible in Checkout​

  • Confirm the plugin is active.
  • Confirm PayIsland is enabled under WooCommerce payments.
  • Confirm Checkout Block support is enabled and available.
  • Try the classic checkout shortcode [woocommerce_checkout] if needed.

callback_url Must Be a URL Address​

  • Use a public HTTPS URL.
  • Do not use localhost.
  • For local testing, use ngrok or another public HTTPS tunnel.

Wrong Amount​

  • PayIsland expects the major currency unit.
  • Do not multiply by 100.
  • For example, send "7000" for NGN 7,000.

Payment Pending​

  • The customer may need to complete 3DS authentication.
  • Verify the transaction again or wait for the webhook or callback.
  • Do not fulfill the order while the transaction is pending.

Logs​

Enable debug logging during testing from the PayIsland payment settings page. View logs in:

WooCommerce > Status > Logs > payisland-woocommerce

Logs can help confirm whether transaction initialization, callbacks, webhooks, and transaction verification are completing as expected.