Description
This plugin adds the Dornapal payment gateway to WooCommerce. The buyer chooses Dornapal at checkout, is redirected to the secure Dornapal payment page, and after paying the order is finalized once the payment is confirmed on the server side.
Features:
- Works with both the classic checkout and the block-based checkout
- Compatible with High-Performance Order Storage (HPOS) and legacy order storage
- Payment confirmation through a signed webhook, even if the buyer never returns to the store
- Optional percentage or fixed-amount discount for buyers who choose Dornapal
- Failure reasons recorded in Persian on the settings page and on the order itself
- Supports Rial (IRR) and Toman (IRT)
Use of an external service
This plugin connects to the Dornapal payment service to process payments and does not work without it. Full details are in the External services section below.
Gateway connection settings for technical administrators
By default the plugin uses the production address https://api.dornapal.ir and you do not need to change it for a live store. The service base address is defined in the DORNAPAL_API_BASE_URL constant. To test against a development environment, define this constant in wp-config.php; a value defined there takes priority. Enter only the service host and do not append /api/v1/payments.
Do not change the service address or the merchant key while you have pending payments.
Dornapal payment discount
In the gateway settings you can define a percentage or fixed-amount discount for buyers who choose Dornapal. For percentage discounts you can set a maximum amount, and for both types you can require a minimum cart amount.
The discount stays on the order only while Dornapal is the payment method. If the buyer picks another gateway, the discount line is removed from the order, the total is recalculated and a note is added to the order. The discount is always rounded so that the remaining amount stays valid for Dornapal: a whole number, a multiple of 10 on Rial stores, and never below the gateway minimum.
The discount label is shown to the buyer in the order totals table, and a short summary of the discount is added automatically below the gateway title so the buyer knows about it before choosing.
Seeing why a payment failed
Gateway errors are recorded in three places for you, and none of them is shown to the buyer:
- The “Latest gateway errors” table at the bottom of the Dornapal settings page, with the reason, stage, order number and tracking code.
- A private note on the order itself.
- WooCommerce logs with the source dornapal, under WooCommerce > Status > Logs.
If the error is a configuration error (for example an invalid merchant key, an inactive merchant or insufficient credit), a persistent warning is shown on the settings page and clears itself after the first successful payment. The tracking code and payment ID of each order are shown on the order edit screen so you can include them in a ticket to Dornapal support.
Webhook
Copy the webhook URL from the gateway settings and register it in the Dornapal merchant panel. Then enter the webhook security key in the WooCommerce settings. The webhook URL is read-only and accepts POST requests on the site REST route dornapal/v1/webhook.
Every message is verified with an HMAC-SHA256 signature. A message without a valid signature, with a timestamp outside the allowed window, or with an invalid event ID is rejected.
The stored merchant key and webhook key are never printed in the settings HTML and cannot be read through the WooCommerce REST API. Leaving these fields empty keeps the previous value; the “Remove the saved key” option clears it, and the gateway is then disabled automatically. Keys are stored in the native WooCommerce settings without an extra encryption layer.
The internal constant DORNAPAL_WEBHOOK_TOLERANCE can be defined in wp-config.php before the plugin loads. Its default is 900 seconds, measured from the time the message was sent; this is the window recommended by the Dornapal documentation and it covers webhook retries (up to about seven minutes after the event). Lowering it causes valid retries to be rejected. The server clock must be synchronized, otherwise all webhooks are rejected.
Payment behavior for developers
Every Create call carries a new UUID in the Idempotency-Key header. A retry after a connection error within the same run reuses the UUID and data of that request. Version 1 retries such a request at most once, does not automatically retry definitive HTTP errors, and does not store keys or attempts. The buyer is redirected exactly to the returned paymentUrl, which must be HTTPS.
Only a return with the OK status triggers an immediate Verify. Other return statuses only show a message and never mark the order as successful. A webhook message with a valid signature also runs Verify. Success requires code 100 or 201, the CONFIRMED status in payment.status, a matching authority, a matching orderId when present, and matching amounts.requested taking the currency into account. The Payable value is not compared.
The buyer return route is public and unsigned, so Verify runs at most 5 times per minute for each authority. The webhook is not subject to this limit.
After a successful Verify the plugin reloads the order and checks is_paid(); if the order is not yet paid, payment_complete() is called with the tracking code. WooCommerce determines the final order status and runs the stock and order-processing hooks. No lock, queue, event history or custom table is added.
The plugin stores only _dornapal_authority, _dornapal_tracking_code, _dornapal_requested_amount and _dornapal_requested_currency on the order. Starting a new payment replaces these values; a message about an old authority cannot complete the order.
External services
This plugin connects to the Dornapal payment service to create and verify payments. It will not function without this connection.
When data is sent: a request is made to the Dornapal API at two points only — when a buyer places an order and is sent to the payment page, and when a payment is verified (either when the buyer returns to the shop, or when Dornapal sends a signed webhook to the site).
What is sent: the shop’s merchant key, the WooCommerce order ID, the order total and currency, a short order description containing the order ID, and the shop’s return URL. No customer name, address, email, phone number, or card data is sent by this plugin.
What is received: a payment identifier, a tracking code, a payment page URL, and the payment status and amounts.
Endpoints: https://api.dornapal.ir/api/v1/payments/request and https://api.dornapal.ir/api/v1/payments/verify. The site also exposes dornapal/v1/webhook to receive signed confirmations from Dornapal.
Service provider: Dornapal — https://dornapal.ir
API documentation: https://docs.dornapal.ir
Service status: https://status.dornapal.ir
Pricing and service conditions: https://dornapal.ir/fa/pricing
Installation
- Install and activate the plugin from Plugins > Add New, or place the dornapal-for-woocommerce folder in wp-content/plugins. WooCommerce must be active.
- Go to WooCommerce > Settings > Payments > Dornapal.
- Get your merchant key from the Dornapal panel and enter it.
- Copy the webhook URL from the same page and register it in the Dornapal panel under Gateway settings > Webhook. Then enter the webhook key in the plugin settings. The gateway cannot be enabled without the webhook key.
- Enable the gateway and save the settings.
The store currency must be Rial (IRR) or Toman (IRT). The order amount must be equivalent to between 1,000 and 29,000,000 Toman, with no decimal part, and amounts in Rial must be a multiple of 10. If the cart amount is outside this range, Dornapal is not shown at checkout.
The site must use HTTPS; Dornapal does not accept insecure return and webhook URLs.
FAQ
-
Why is Dornapal not shown at checkout?
-
One of these: the gateway is not enabled, the merchant key or webhook key has not been entered, the store currency is not Rial or Toman, or the cart amount is outside the range Dornapal allows. The status cards at the top of the plugin settings page show exactly which one applies.
-
Why is the webhook key required?
-
The webhook is the only way the store learns about a payment confirmation when the buyer does not return to the store after paying, which is common with card-to-card payments. Without it, completed payments may never turn into finalized orders.
-
An order was paid but is still pending. What should I do?
-
First make sure the webhook URL is registered in the Dornapal panel and that the webhook key in the plugin matches it. Then check the “Latest gateway errors” table at the bottom of the settings page and the notes of that order. The server clock must also be synchronized, otherwise all webhooks are rejected.
-
Does the plugin create database tables?
-
No. The plugin only uses WooCommerce settings, order meta and a few entries in the options table. When the plugin is deleted, these options are removed.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Dornapal for WooCommerce” is open source software. The following people have contributed to this plugin.
ContributorsTranslate “Dornapal for WooCommerce” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.0.0
- Initial release.
