Plan an eSewa web checkout before writing the integration

Begin by confirming which eSewa product your merchant account is approved to use. This guide reviews the documented ePay architecture and proposes an implementation checklist. It does not provide a finished Next.js integration or claim that a sandbox payment was executed.

Read the selected product contract

The reviewed ePay documentation describes a hosted browser flow, a signed return response and a transaction-status verification route. It specifies HMAC-SHA256 for its signature flow. These details should not be assumed to describe every eSewa product.

Record the documentation page and review date in your project notes. Obtain the merchant account’s approved configuration and test environment before implementing request signing or deciding how results will be verified.

Reference: eSewa — ePay documentation ↗

Keep the order calculation on the server

Create the order and expected amount from server-controlled product data. Give each payment attempt a unique reference and associate it with the order before handing the customer to checkout. Browser-supplied totals should not become your authoritative price.

In a Next.js application, keep secret-bearing operations in server-side code. Do not expose a signing secret through a public environment variable, browser bundle or copied documentation example.

Design the return as a verification boundary

Parse incoming data defensively and validate it using the selected provider contract. Match the verified result to the stored merchant context, reference and amount before updating your own order state.

Keep pending, failed and unknown outcomes distinct. A customer might close a tab or return twice; neither event should produce duplicate fulfilment. An incomplete response should remain reviewable rather than becoming a successful order for convenience.

Test before production approval

Prepare cases for the successful path, cancellation, mismatched amounts, modified return data, a delayed response and repeated returns. Assert that only the verified matching result can fulfil the order.

Run those cases in the provider-approved environment and record the actual results. Complete any provider review required for your account. Documentation review is useful preparation, but it must not be described as a completed end-to-end payment test.

Review the wider Nepal payment integration checklist →