Install
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.zipNo 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 fileezbill-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
- Copy this folder into
wp-content/plugins/namedezbill-payments(e.g.zip -r ezbill-payments.zip ezbill-payments/and upload via Plugins > Add New > Upload). - Activate it. Set WooCommerce > Settings > General > Currency to PKR.
- 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)
- Sandbox API key (
- 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 withX-EZBILL-Signature: v1=<hex>, rejected ifX-EZBILL-Timestampis more than 300 s away. Idempotency key isevent + 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
- 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
cloudflaredorngrokfor a local site); without it, the status poll on the payment page still confirms the order. - Place an order. You land on the payment page with a QR and countdown.
- 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.
- 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.
- 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"). - 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) andWC 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 SVNassets/folder). - Publish terms of service and privacy policy pages on ezbill.pk and link them
in the "External services" section of
readme.txt.