WooCommerce

​

Structure

woocommerce/
  nomba-for-woocommerce.php          plugin bootstrap, gateway registration
  readme.txt                         WordPress.org manifest, install + FAQ
  uninstall.php                      cleanup on delete
  includes/
    class-wc-gateway-nomba.php       WC_Payment_Gateway subclass (Nomba)
    class-nomba-client.php           token issue (cached) + order/verify/refund
    class-nomba-signature.php        nine-field HMAC verification, 300s window
    class-nomba-webhook.php          REST webhook handler, re-verifies
    class-wc-gateway-duro.php        second gateway (Duro hosted checkout)
    class-duro-client.php / -signature.php / -webhook.php

​

Install

1. Upload the plugin zip via Plugins, Add New, Upload Plugin, then activate. (Build it with bash tools/build.sh, which produces dist/nomba-woocommerce.zip.)
2. Open WooCommerce, Settings, Payments.
3. Open the Nomba payment method and enter the Account ID, Client ID, and Client secret from the Nomba dashboard (API Keys). Use the parent (business) Account ID; a sub-account ID is rejected at authentication. Test keys work with test mode on.
4. Enter the Webhook signature key from the dashboard webhook settings. Optionally set a Sub-account ID to deposit payments into a sub-account.
5. In the Nomba dashboard, set the webhook URL to https://your-store.example/wp-json/nomba/v1/webhook.
6. Enable the gateway and save.

​

Nomba lifecycle

1. process_payment creates a Nomba checkout order (POST {prefix}/order) and redirects the shopper to data.checkoutLink. The order stores _nomba_order_reference and _nomba_mode.
2. verify_on_return calls the verify endpoint and completes the order only on paid plus a matching amount.
3. The webhook (POST /wp-json/nomba/v1/webhook) verifies the nine-field HMAC signature from the nomba-signature header with the nomba-timestamp header, enforces a 300-second replay window, then re-verifies the transaction with the Nomba API (verify_order, GET {prefix}/transaction) before doing anything else. The API response is the source of truth, not the webhook payload. It cross-checks the verified amount and currency, stores _nomba_transaction_id from the verified paymentReference, and completes the order. Re-verification applies to payment_success only; payment_failed marks an unpaid order failed and payment_reversal marks a paid order refunded, both from the signed event without an extra API call.
4. Refunds run from the WooCommerce order screen through POST {prefix}/refund with the stored transaction id; partial amounts are supported. Refunds use the mode the order was paid in.

​

Environments

​

The Duro gateway

1. process_payment creates a Duro checkout session (POST /v1/checkout/sessions, amount in kobo, mandatory Idempotency-Key header) and redirects to the hosted checkout URL. The order stores _duro_session_id, _duro_token, _duro_mode.
2. verify_on_return calls Duro_Client::get_session and completes the order only when the session status is completed plus a matching amount (kobo).
3. The webhook (POST /wp-json/duro/v1/webhook) verifies the t.rawBody HMAC signature from the duro-signature header, enforces a 300-second replay window, dedupes on duro-event-id, then re-verifies the session with the Duro API before completing on checkout_completed or subscription_payment_success.
4. No refunds. A one-off Duro checkout (kind: one_time) creates no refundable invoice, so the Duro gateway does not declare refunds support; use the Nomba gateway when a refund is required.

​

Error states

​

Tests and demo

docker run --rm -v "$PWD":/repo -w /repo/tools/tests composer:2.7 composer install
docker run --rm -v "$PWD":/repo -w /repo/tools/tests php:8.3-cli vendor/bin/phpunit