WP Manifestindependent plugin directory
manifest / ecommerce / woocommerce-ezbill

EZBILL – Raast QR Payments for WooCommerce

EZBILL Raast QR payments for WooCommerce: customers pay from any bank app, JazzCash or Easypaisa in Pakistan.

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/abdullahzulfiqar653/woocommerce-ezbill/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Accept Raast payments in Pakistan with a dynamic QR code. Customers scan and pay from any bank app, JazzCash or Easypaisa, and the order is marked paid automatically. Built on the EZBILL public API.

  • Plugin slug: ezbill-payments (main file ezbill-payments.php)
  • License: GPLv2 or later
  • Requires: WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+, store currency PKR
  • Docs: https://ezbill.pk/developers/
  • Tested end to end on WordPress 7.1 + WooCommerce 11.2 (Blocks and classic checkout) against the EZBILL sandbox.

The wordpress.org listing text lives in readme.txt.

Install

  1. Copy this folder into wp-content/plugins/ named ezbill-payments (e.g. zip -r ezbill-payments.zip ezbill-payments/ and upload via Plugins > Add New > Upload).
  2. Activate it. Set WooCommerce > Settings > General > Currency to PKR.
  3. WooCommerce > Settings > Payments > EZBILL – Raast QR:
    • Sandbox API key (ez_test_…), live API key (ez_live_…)
    • Test mode on/off (on = sandbox key)
    • Webhook signing secret (from the EZBILL portal)
    • QR expiry in minutes (1–1440, default 30)
  4. Copy the Webhook URL shown in the settings (https://your-store/wp-json/ezbill/v1/webhook) into the EZBILL portal as Your endpoint base URL. EZBILL POSTs to {base}/onego-notification, which the plugin also serves.

Saving the settings checks the active key with POST /v1/auth/token and shows which environment it belongs to.

How it works

Checkout ──► process_payment() ──► POST /v1/qr {amount_minor, reference: order id, expiry_minutes}
                                   order meta: EZBILL id, qr_string, expires_at
         ──► order-pay page: QR (rendered in the browser), amount, countdown
               every 5 s ──► GET /wp-json/ezbill/v1/orders/<id>/status?key=<order key>
                              └─► server: GET /v1/rtp/<id> (cached 4 s) ─► PAID/SETTLED → payment_complete()
               on expiry ──► POST /wp-json/ezbill/v1/orders/<id>/regenerate?key=<order key>
EZBILL ──► POST /wp-json/ezbill/v1/webhook/onego-notification (HMAC-signed)
               payment.received → payment_complete(<EZBILL id>)
               payment.settled  → note + settled time
               rtp.rejected     → order Failed (customer can retry)
               rtp.expired      → note (new QR on return to the page)
  • Amounts are integer paisa (Rs 1 = 100), converted from the order total without floating-point drift.
  • The API key is used server-side only. The browser talks to the store's own REST routes, authorised by the WooCommerce order key.
  • Webhook verification: HMAC_SHA256(secret, timestamp + "." + raw_body) compared in constant time with X-EZBILL-Signature: v1=<hex>, rejected if X-EZBILL-Timestamp is more than 300 s away. Idempotency key is event + correlation_id + id; a repeat returns 200.
  • A paid event is only accepted if the EZBILL id was issued for that order and the amount matches the QR. A mismatch puts the order On hold with a note.
  • 503 / network errors show "temporarily unavailable, try again", never a credentials error.
  • The QR library is qrcode-generator 1.4.4 (MIT), bundled at assets/js/vendor/qrcode.js. Nothing is loaded from a CDN.

Files

File Purpose
ezbill-payments.php Plugin header, HPOS + Blocks compatibility, bootstrap
includes/class-ezbill-wc-api.php EZBILL API client (wp_remote_request)
includes/class-ezbill-wc-gateway.php WC_Payment_Gateway: settings, checkout, QR box
includes/class-ezbill-wc-rest.php Webhook, status poll and regenerate routes
includes/class-ezbill-wc-blocks.php Cart & Checkout Blocks integration
assets/js/ezbill-checkout.js QR render, countdown, polling, redirect
assets/js/ezbill-blocks.js Blocks payment-method registration (no build step)
uninstall.php Deletes plugin settings (keeps order records)

Testing against the sandbox

  1. Test mode on, sandbox key saved, webhook URL + secret configured. Your store must be reachable from the internet for webhooks (use a tunnel such as cloudflared or ngrok for a local site); without it, the status poll on the payment page still confirms the order.
  2. Place an order. You land on the payment page with a QR and countdown.
  3. The sandbox pays every QR automatically a few seconds after creation, so within ~5–10 s the page redirects to the thank-you page and the order is Processing with the EZBILL id as transaction ID.
  4. An order total ending in 98 paisa (e.g. Rs 100.98) is rejected by the sandbox: the order goes Failed and the page offers a new QR.
  5. The sandbox pays QRs almost at once, so natural expiry is hard to reach there. The renewal path (/regenerate) is the same one used after a rejection in step 4 ("Generate a new QR code").
  6. Logs: WooCommerce > Status > Logs, source ezbill (enable Debug log).

Developers running a local EZBILL backend can point the plugin at it from wp-config.php (there is deliberately no settings field for this):

define( 'EZBILL_API_BASE', 'http://127.0.0.1:8811' ); // or filter ezbill_wc_api_base

Manual webhook test (replace secret, URL and ids):

SECRET=whsec_xxx; TS=$(date +%s)
BODY='{"amount_minor":10000,"correlation_id":"c1","event":"payment.received","fee_minor":50,"id":"<ezbill id>","kind":"QR","reference":"<order id>","status":"PAID"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -i -X POST https://your-store/wp-json/ezbill/v1/webhook \
  -H 'Content-Type: application/json' -H "X-EZBILL-Timestamp: $TS" \
  -H "X-EZBILL-Signature: v1=$SIG" -H 'X-Correlation-Id: c1' --data "$BODY"

Before submitting to wordpress.org

  • Bump Tested up to (readme) and WC tested up to (plugin header) to the current releases.
  • Run the Plugin Check plugin and phpcs --standard=WordPress.
  • Add screenshots (assets/screenshot-1.png, … in the SVN assets/ folder).
  • Publish terms of service and privacy policy pages on ezbill.pk and link them in the "External services" section of readme.txt.