esewa

eSewa is Nepal's leading digital wallet, enabling instant online payments for mobile recharges, utility bills (electricity, internet, water, TV), insurance premiums, bus, airline, and movie tickets, and many more services.

The eSewa Payment Gateway module integrates eSewa into Drupal Commerce using the official eSewa ePay v2 API with HMAC-SHA256 cryptographic signature verification. When a customer selects eSewa at checkout they are securely redirected to the eSewa payment page. After completing payment, eSewa redirects back to your site with a base64-encoded, cryptographically signed response. The module verifies the signature before recording the payment, preventing fraudulent or tampered responses from ever fulfilling an order.

Key features:

• Full eSewa ePay v2 API integration (HMAC-SHA256 signed POST form)
• Cryptographic response verification via remotemerge/esewa-php-sdk
• Replay-attack prevention (transaction UUID cross-check)
• Amount tamper detection (±0.01 NPR tolerance check)
• Automatic sandbox credentials in test mode — no configuration required
• Drupal Commerce event dispatch on payment success / failure
• Hook support for custom success / failure messages
• Form validation: live credentials required when mode is set to Live
• Supports Drupal 10 and Drupal 11

Supported currencies: NPR (Nepalese Rupee) only.

To submit bug reports and feature suggestions, or to track changes:
https://www.drupal.org/project/issues/esewa

REQUIREMENTS

This module requires the following:

Drupal modules

• Drupal Commerce
  ^3.0 (includes commerce_order, commerce_payment, commerce_cart)

PHP

• PHP 8.1 or higher
• PHP extensions: ext-curl, ext-json (required by the SDK)

Composer library (installed automatically)

• 
  remotemerge/esewa-php-sdk ^4.0
  

INSTALLATION

Step 1 — Install via Composer

Always install this module and its PHP dependency via Composer so that autoloading of the SDK is handled automatically. From your Drupal project root, run:

	composer require drupal/esewa

This single command will:

1. Download the drupal/esewa module into modules/contrib/esewa
2. Automatically install remotemerge/esewa-php-sdk ^4.0 into vendor/
3. Regenerate the Composer autoloader

Custom module note: If you are managing this as a custom module in modules/custom/esewa, add only the SDK dependency:
composer require remotemerge/esewa-php-sdk ^4.0

Step 2 — Enable the module

Via Drush (recommended):

	
drush en esewa -y
drush cr

Via the Drupal UI:

1. Navigate to Administration » Extend ( /admin/modules)
2. Find eSewa Payment Gateway under the Commerce package
3. Tick the checkbox and click Install
4. Clear caches via drush cr or Administration » Configuration » Performance

Step 3 — Verify the SDK library

	php -r "require 'vendor/autoload.php'; echo class_exists('RemoteMerge\Esewa\EsewaFactory') ? 'SDK OK' : 'SDK MISSING';"

Expected output: SDK OK. If you see SDK MISSING, run composer install and then drush cr.

CONFIGURATION

Set your store currency to NPR

eSewa only processes NPR (Nepalese Rupee) payments. Before adding the gateway:

1. Navigate to Administration » Commerce » Configuration » Currencies and confirm NPR is present. If not, click + Add currency and add Nepalese Rupee (NPR).
2. Navigate to Administration » Commerce » Configuration » Stores, edit your store, and set NPR as the default currency.

The module will display an error at checkout and refuse to build the payment form if the order currency is not NPR.

Add the payment gateway

1. Navigate to Administration » Commerce » Configuration » Payment gateways ( /admin/commerce/config/payment-gateways)
2. Click + Add payment gateway
3. In the Plugin dropdown select eSewa
4. Fill in the fields described below
5. Click Save

Gateway configuration fields

Field Required Description Name Yes Internal admin label, e.g. eSewa Display name Yes Customer-facing label shown at checkout, e.g. Pay with eSewa Mode Yes Test (development / staging) or Live (production) Test Product Code No Leave blank to use the eSewa sandbox default EPAYTEST automatically Test Secret Key No Leave blank to use the eSewa sandbox default automatically Live Product Code Live only Merchant code from your eSewa Merchant Dashboard, e.g. NP-ES-YOURCODE Live Secret Key Live only HMAC-SHA256 key from your eSewa Merchant Dashboard. Stored securely. Status Yes Set to Enabled

Test mode: When Mode is set to Test, the official eSewa sandbox credentials ( EPAYTEST / 8gBm/:&EnhH.1/q) are applied automatically. You do not need to enter a Product Code or Secret Key for testing.

TEST CREDENTIALS

Official eSewa sandbox credentials from the eSewa Developer Portal. No real money is involved in test mode.

eSewa test user accounts

Field Value eSewa ID 9711111111 / 9711111112 / 9711111113 / 9711111114 Password Nepal@123 MPIN 1122
(mobile app only) OTP / Token 123456

Merchant / SDK sandbox credentials (applied automatically)

Field Value Product Code EPAYTEST Secret Key 8gBm/:&EnhH.1/q

eSewa environment URLs (for reference)

Environment Purpose URL Test Payment form POST https://rc-epay.esewa.com.np/api/epay/main/v2/form Test Transaction status check https://rc.esewa.com.np/api/epay/transaction/status/ Production Payment form POST https://epay.esewa.com.np/api/epay/main/v2/form Production Transaction status check https://esewa.com.np/api/epay/transaction/status/

These URLs are managed automatically by the SDK based on the configured environment.

PRODUCTION SETUP

Step 1 — Register as an eSewa Merchant

1. Visit https://merchant.esewa.com.np
2. Create or log in to your eSewa Merchant account
3. Complete the KYC / merchant verification process
4. eSewa will issue your live Product Code and Secret Key

Step 2 — Switch the gateway to Live mode

1. Navigate to Administration » Commerce » Configuration » Payment gateways
2. Edit your eSewa gateway
3. Change Mode to Live
4. Enter your Live Product Code
5. Enter your Live Secret Key
6. Click Save

Security tip: Store the Secret Key in an environment variable or a secrets manager — never commit it to version control. You can inject it via settings.php:
$config['commerce_payment.commerce_payment_gateway.esewa']['configuration']['live_secret_key'] = getenv('ESEWA_SECRET_KEY');

Step 3 — Confirm HTTPS

Both callback URLs ( /esewa/success and /esewa/cancel) must be served over HTTPS in production to prevent response interception.

PAYMENT FLOW

The module implements the three-step eSewa ePay v2 flow:

1. INITIATE — The module builds a signed POST form via the SDK. The SDK generates an HMAC-SHA256 signature over total_amount, transaction_uuid, and product_code. The customer's browser auto-submits this form to the eSewa checkout page.

2. VERIFY — After the customer completes payment, eSewa redirects to /esewa/success?data=<base64>. The module decodes the response, verifies the HMAC-SHA256 signature via the SDK, cross-checks the transaction_uuid (replay-attack prevention), confirms the status is COMPLETE, and validates total_amount matches the stored order total (±0.01 NPR tamper detection).

3. COMPLETE — All checks passed: a commerce_payment entity is saved in completed state, the order is advanced to the complete checkout step, the esewa.payment_success event is dispatched, and the customer is redirected to the order confirmation page.

On cancel/failure — eSewa redirects to /esewa/cancel. The module rolls the order back to the previous checkout step (so the customer can retry), dispatches the esewa.payment_failure event, and shows a cancellation warning.

eSewa ePay v2 request fields

Field Required Description amount Yes Base product/service price tax_amount Yes Tax amount (use 0 if none) product_service_charge Yes Service charge (use 0 if none) product_delivery_charge Yes Delivery charge (use 0 if none) total_amount Yes Sum of all above fields transaction_uuid Yes Unique order identifier — alphanumeric and hyphens only product_code Yes Merchant product code assigned by eSewa success_url Yes Your absolute /esewa/success callback URL failure_url Yes Your absolute /esewa/cancel callback URL signed_field_names Yes total_amount,transaction_uuid,product_code signature Yes HMAC-SHA256 base64-encoded signature

eSewa success response (decoded from ?data=)

	
{
  "transaction_code": "0007G36",
  "status": "COMPLETE",
  "total_amount": "1000.0",
  "transaction_uuid": "your-uuid-here",
  "product_code": "EPAYTEST",
  "signed_field_names": "transaction_code,status,total_amount,transaction_uuid,product_code,signed_field_names",
  "signature": "62GcfZTmVkzhtUeh+QJ1AqiJrjoWWGof3U+eTPTZ7fA="
}

Transaction status values

Status Meaning COMPLETE Payment completed successfully PENDING Payment initiated but not yet completed FULL_REFUND Full payment refunded to customer PARTIAL_REFUND Partial payment refunded AMBIGUOUS Payment is in an uncertain / halted state NOT_FOUND Session expired or transaction does not exist CANCELED Payment cancelled or reversed by eSewa

TROUBLESHOOTING

Module does not appear in the Payment gateways plugin list

	drush en esewa -y && drush cr

Verify the @CommercePaymentGateway annotation block is intact in src/Plugin/Commerce/PaymentGateway/EsewaCheckoutCheckout.php.

"Class not found" / SDK autoload errors

	
composer require remotemerge/esewa-php-sdk ^4.0
composer dump-autoload
drush cr

"eSewa supports NPR only" message at checkout

Your Commerce store currency is not NPR. Navigate to Administration » Commerce » Configuration » Stores and set the default currency to NPR (Nepalese Rupee).

Payment verified but order does not advance to "complete"

Ensure your Commerce checkout flow includes a complete step. Navigate to Administration » Commerce » Configuration » Checkout flows and verify the step exists and is correctly positioned.

Signature verification failure / "Invalid signature" in logs

• In live mode: confirm the Secret Key in gateway settings exactly matches the key in your eSewa Merchant Dashboard, including all special characters.
• In test mode: the key 8gBm/:&EnhH.1/q is applied automatically. If you see this error in test mode, clear all caches and retry.
• Verify your server's system clock is accurate (NTP sync recommended).

"Amount mismatch" in Drupal logs

eSewa returned a total_amount that differs from the stored order total by more than ±0.01 NPR. Check whether order prices are being modified after the payment form is built, or investigate currency rounding configuration.

"Transaction UUID mismatch" in Drupal logs

The transaction_uuid in eSewa's response does not match the UUID stored in the PHP session. This protects against replay attacks. Possible causes: session expiry, the user opening multiple browser tabs, or an actual tampered response. The payment is safely rejected in all cases.

Viewing eSewa-specific log messages

	drush watchdog:show --type=esewa --count=50

Or via UI: Administration » Reports » Recent log messages ( /admin/reports/dblog) — filter by Type: esewa.

DEVELOPER REFERENCE

Hooks

hook_esewa_success_message(string &$message)

Customise the status message displayed to the customer after a successful payment.

	
/**
 * Implements hook_esewa_success_message().
 */
function mymodule_esewa_success_message(string &$message): void {
  $message = t('<strong>Thank you!</strong> Your eSewa payment has been received.');
}

hook_esewa_failure_message(string &$message)

Customise the warning message displayed when a payment is cancelled or fails.

	
/**
 * Implements hook_esewa_failure_message().
 */
function mymodule_esewa_failure_message(string &$message): void {
  $message = t('Your eSewa payment was not completed. You have not been charged.');
}

Events

The module dispatches Symfony events that any module can subscribe to.

Constant Event string Fired when EsewaCheckoutEvents::PAYMENT_SUCCESS esewa.payment_success HMAC signature verified, payment entity created EsewaCheckoutEvents::PAYMENT_FAILURE esewa.payment_failure User cancels or gateway onCancel() is called

Example event subscriber:

	
// mymodule/src/EventSubscriber/EsewaEventSubscriber.php
namespace Drupal\mymodule\EventSubscriber;

use Drupal\esewa\Event\EsewaCheckoutEvents;
use Drupal\esewa\Event\EsewaCheckoutPaymentEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class EsewaEventSubscriber implements EventSubscriberInterface {

  public static function getSubscribedEvents(): array {
    return [
      EsewaCheckoutEvents::PAYMENT_SUCCESS => 'onPaymentSuccess',
      EsewaCheckoutEvents::PAYMENT_FAILURE => 'onPaymentFailure',
    ];
  }

  public function onPaymentSuccess(EsewaCheckoutPaymentEvent $event): void {
    $order = $event->getOrder();
    // e.g. trigger a receipt email, update inventory, etc.
  }

  public function onPaymentFailure(EsewaCheckoutPaymentEvent $event): void {
    $order = $event->getOrder();
    // e.g. restore reserved stock, send a cancellation notification, etc.
  }
}

Register the subscriber in mymodule.services.yml:

	
services:
  mymodule.esewa_event_subscriber:
    class: Drupal\mymodule\EventSubscriber\EsewaEventSubscriber
    tags:
      - { name: event_subscriber }

Session keys

The module stores these scalar values in the PHP session during the payment redirect. They are cleared immediately after the callback is processed.

Key Type Description esewa_order_id int Commerce order ID esewa_gateway_id string Payment gateway entity machine name esewa_transaction_uuid string UUID sent to eSewa — used for replay-attack detection esewa_total_amount float Order total in NPR — used for amount tamper detection esewa_is_test bool Whether the gateway was in test mode when the form was built

Gateway plugin API

Public methods available on EsewaCheckoutCheckout:

Method Signature Description createEsewaClient() (string $success_url, string $failure_url): EpayInterface Returns a fully configured SDK client for the current mode. In test mode, sandbox credentials are applied automatically. completePayment() (OrderInterface $order, string $remote_id, string $remote_state): PaymentInterface Creates and saves a commerce_payment entity in completed state and dispatches the success event.

RUNNING TESTS

The module ships with PHPUnit unit tests covering the plugin's core business logic. No database or browser is required.

	
# From the module directory:
cd modules/custom/esewa

php ../../../vendor/bin/phpunit \
  --configuration phpunit.xml.dist \
  tests/src/Unit/ \
  --testdox

File What it covers EsewaCheckoutEventsTest Event name constants EsewaCheckoutPaymentEventTest Payment event object construction and order accessor EsewaCheckoutCheckoutTest defaultConfiguration(), createEsewaClient() (test/live modes, sandbox fallbacks, missing-credential exceptions), completePayment() (entity creation, event dispatch, test/live flags), onCancel()