Skip to content

Payments · Engineering · Guides

Integrate eSewa in Nepal with TolaPay

One API call creates an eSewa checkout; TolaPay runs the ePay v2 form, verifies eSewa's response server-side and sends you a signed invoice.paid webhook. A runnable curl example, the response and the webhook to handle.

Written by
TolaPay team
Published
Reading time
5 min read

eSewa's ePay v2 is a redirect flow: you post a signed form, the customer pays in eSewa, and eSewa sends them back with a signed response that you must verify before you trust it. With TolaPay you keep your own eSewa merchant account and skip that code. Your server makes one API call, the customer pays, and you act on a webhook. This guide is the payment gateway for Nepal applied to eSewa alone; the eSewa feature page has the overview.

Before you start

  • An eSewa merchant account. Apply with eSewa; they ask for documents such as your business registration and PAN or VAT certificate. For testing, eSewa's sandbox merchant (EPAYTEST) works in TolaPay's test mode.
  • A TolaPay workspace with eSewa connected under Integrations: paste the merchant code and secret key. eSewa offers no way to check a secret key up front, so the API lists the rail as connected_unverified until the first verified payment. It is usable at checkout from the moment you save it.
  • A test API key (tola_test_…) from Developers. Test and live credentials are kept separate.

1. Create a checkout restricted to eSewa

allowed_providers limits what the hosted page offers. Provide exactly one item: plan_id for a subscription, product_id for a one-time purchase, invoice_id to collect an open invoice, or wallet_top_up_cents. Pass customer to create the customer when they pay, or customer_id for an existing one.

curl https://api.tola.com.np/api/v1/checkouts \
  -H "Authorization: Bearer $TOLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-T12-0427" \
  -d '{
    "product_id": "prod_m3n8p2qv7r4xw9ka1tyb",
    "amount_cents": 250000,
    "customer": { "name": "Phewa Studio", "email": "accounts@phewa.example", "phone": "9800000000" },
    "allowed_providers": ["esewa"],
    "success_url": "https://app.phewa.example/orders/T12-0427?checkout={CHECKOUT_ID}",
    "cancel_url": "https://app.phewa.example/orders/T12-0427",
    "metadata": { "order_ref": "T12-0427" }
  }'

Money is always an integer in paisa: 250000 is NPR 2,500.00. The Idempotency-Key header is optional, but with it a retried request replays the same checkout for 24 hours instead of creating a second one.

2. The response

The API answers 201 Created with a checkout session. Trimmed to the fields you will use:

{
  "id": "cs_a1b2c3d4e5f6g7h8i9j0",
  "public_id": "chk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "url": "https://app.tola.com.np/c/chk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "kind": "one_time",
  "status": "pending",
  "customer": { "name": "Phewa Studio", "email": "accounts@phewa.example", "phone": "9800000000" },
  "product_name": "Studio licence",
  "line_items": [{ "description": "Studio licence", "amount_cents": 250000 }],
  "subtotal_cents": 250000,
  "tax_cents": 32500,
  "total_cents": 282500,
  "tax_inclusive": false,
  "currency": "NPR",
  "available_payment_methods": [
    { "provider": "esewa", "label": "eSewa", "flow": "redirect" }
  ],
  "payment_provider": null,
  "payment_attempts": 0,
  "success_url": "https://app.phewa.example/orders/T12-0427?checkout={CHECKOUT_ID}",
  "cancel_url": "https://app.phewa.example/orders/T12-0427",
  "metadata": { "order_ref": "T12-0427" },
  "invoice_id": null,
  "payment_id": null,
  "result": null,
  "expires_at": "2026-11-14T09:30:00Z",
  "created_at": "2026-11-13T09:30:00Z"
}

Send the customer to url. The chk_… public id is the capability for that page, so it needs no login. Store id against your order; invoice_id and payment_id are filled in once the payment completes.

3. What happens on the hosted page

The customer picks eSewa. TolaPay calls its own POST /api/v1/checkouts/{id}/pay, which returns a redirect_url pointing at /api/v1/checkouts/{id}/redirect/esewa. That endpoint renders a tiny HTML page that form-posts the signed ePay v2 request to eSewa, so the signature never lives in your code. The customer approves in eSewa and comes back to /api/v1/checkouts/{id}/return. TolaPay ignores the query parameters there, verifies the payment with eSewa's status check, fulfils the checkout and redirects to the hosted page with ?result=completed (or failed, cancelled, pending), and from there to your success_url with {CHECKOUT_ID} replaced by the public id.

If you prefer the same checkout to open on a phone, the hosted page shows a QR of url; scanning it opens the same session, where eSewa's app is a tap away.

4. Handle invoice.paid

The redirect is a user-experience event. The payment is real when TolaPay says so, and it says so with a webhook. Register an endpoint under Developers (or POST /api/v1/webhook_endpoints) subscribed to invoice.paid. Every delivery carries a Tola-Signature header, t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>, and a Tola-Event header with the type. data is the Invoice:

{
  "id": "we_a1b2c3d4e5f6g7h8i9j0",
  "type": "invoice.paid",
  "created_at": "2026-11-13T09:34:12Z",
  "organization_id": "org_a1b2c3d4e5f6g7h8i9j0",
  "data": {
    "id": "inv_a1b2c3d4e5f6g7h8i9j0",
    "number": "TOLA-2026-0042",
    "customer_id": "cus_7k2mq9vd4r8xw3ba6tyn",
    "customer_name": "Phewa Studio",
    "customer_email": "accounts@phewa.example",
    "subscription_id": null,
    "status": "paid",
    "currency": "NPR",
    "lines": [
      { "kind": "base", "description": "Studio licence", "units": 1, "unit_amount_cents": 250000, "amount_cents": 250000, "metric_code": null }
    ],
    "subtotal_cents": 250000,
    "discount_cents": 0,
    "credits_cents": 0,
    "tax_rate_pct": 13,
    "tax_inclusive": false,
    "tax_cents": 32500,
    "total_cents": 282500,
    "amount_paid_cents": 282500,
    "amount_due_cents": 0,
    "payment_status": "succeeded",
    "paid_at": "2026-11-13T09:34:11Z",
    "pdf_url": "/api/v1/invoices/inv_a1b2c3d4e5f6g7h8i9j0/pdf",
    "created_at": "2026-11-13T09:34:11Z"
  }
}

Your handler should:

  1. Recompute the HMAC over "<t>.<raw body>" with your whsec_… secret, compare in constant time, and reject anything whose t is more than five minutes old.
  2. Look up the event id; if you have processed it, return 200 and stop. Failed deliveries are retried after 1, 5 and 30 minutes, then 2 and 12 hours, so duplicates are normal.
  3. Match the invoice to your order and fulfil it, then respond with any 2xx within 10 seconds. The invoice does not name the checkout, so keep the checkout id from step 2 against your order: GET /api/v1/checkouts/{id} shows status: "completed" and the invoice_id once paid. If you would rather be told, subscribe to payment.succeeded as well; its data is a Payment that carries both checkout_session_id and invoice_id.

The webhook handler guide goes through each habit. If you want the eSewa reference for reconciliation, GET /api/v1/payments/{id} returns provider_reference, which is eSewa's transaction_code.

Subscriptions on eSewa

eSewa has no recurring mandate, so a subscription checkout on eSewa uses collection_method: "invoice_link": each renewal invoice goes to the customer as a link and a reminder, and they pay it in eSewa. invoice.paid fires for each renewal exactly as above.

Refunds

The API has no eSewa refund call. Refund in your eSewa merchant dashboard, then record it with POST /api/v1/payments/{id}/refund and "method": "manual" so the ledger and the invoice agree.

Next step

Run the curl above with a tola_test_ key and eSewa's sandbox credentials, pay the checkout yourself, and watch the delivery arrive under Developers → Webhooks. When you are ready to take Khalti too, add "khalti" to allowed_providers; the Khalti guide covers the differences. Live payments are enabled for businesses in the closed pilot; join the waiting list for a pilot code.

Sources

  1. 01TolaPay API — OpenAPI document
  2. 02eSewa developer documentation (ePay)