Payments · Engineering · Guides
Khalti payment gateway integration with TolaPay
Create a Khalti checkout with one API call, open it straight on the wallet, mobile banking or connectIPS, and confirm payment from a signed invoice.paid webhook. Runnable curl, the response and the webhook payload.
- Written by
- TolaPay team
- Published
- Reading time
- 5 min read
Khalti's KPG-2 ePayment is two calls and a redirect: initiate a payment, send the customer to Khalti, then look the payment up before you believe the return URL. It also carries more than the wallet: e-banking and mobile banking at every bank Khalti routes to, connectIPS and SCT. TolaPay runs the initiate, the return and the lookup for you, and settles to your own Khalti merchant account. This is the payment gateway for Nepal narrowed to Khalti; the Khalti feature page has the overview.
Before you start
- A Khalti merchant account. Register with Khalti and copy the secret key from your merchant dashboard. Khalti's sandbox keys work in TolaPay's test mode.
- Khalti connected under Integrations in TolaPay. When you save the key, TolaPay verifies it by initiating an NPR 10 payment with Khalti and discarding it, so a wrong key fails immediately with
422 validation_error. - A test API key (
tola_test_…) from Developers.
1. Create a checkout restricted to Khalti
For a subscription, pass plan_id and the number of seats. allowed_providers: ["khalti"] hides the other rails; leave it out to show every connected rail and let the customer choose.
curl https://api.tola.com.np/api/v1/checkouts \
-H "Authorization: Bearer $TOLA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: signup-chautari-0981" \
-d '{
"customer": { "name": "Chautari Labs", "email": "finance@chautari.example", "phone": "9800000000" },
"plan_id": "plan_g4wv8t2kq6m1xr9zb3dn",
"seats": 5,
"allowed_providers": ["khalti"],
"success_url": "https://app.chautari.example/welcome?checkout={CHECKOUT_ID}",
"cancel_url": "https://chautari.example/pricing"
}'
2. The response
201 Created with the checkout session. The fields that matter, taken from the API's schema:
{
"id": "cs_a1b2c3d4e5f6g7h8i9j0",
"public_id": "chk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"url": "https://app.tola.com.np/c/chk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"kind": "subscription",
"status": "pending",
"customer": { "name": "Chautari Labs", "email": "finance@chautari.example", "phone": "9800000000" },
"plan": { "id": "plan_g4wv8t2kq6m1xr9zb3dn", "name": "Growth", "interval": "monthly", "features": [] },
"billing_period": "monthly",
"seats": 5,
"line_items": [
{ "description": "Growth plan — base", "amount_cents": 1500000 },
{ "description": "5 seats × NPR 1,000", "amount_cents": 500000 }
],
"subtotal_cents": 2000000,
"tax_cents": 260000,
"total_cents": 2260000,
"tax_inclusive": false,
"currency": "NPR",
"available_payment_methods": [
{ "provider": "khalti", "label": "Khalti", "flow": "redirect", "collection_methods": ["invoice_link", "wallet"] }
],
"payment_provider": null,
"collection_method": null,
"payment_attempts": 0,
"success_url": "https://app.chautari.example/welcome?checkout={CHECKOUT_ID}",
"cancel_url": "https://chautari.example/pricing",
"subscription_id": null,
"invoice_id": null,
"payment_id": null,
"result": null,
"expires_at": "2026-11-14T09:30:00Z",
"created_at": "2026-11-13T09:30:00Z"
}
Redirect the customer to url. collection_methods tells you how renewals will be collected: Khalti is not a recurring rail in the API, so a Khalti subscription renews by invoice_link (each renewal invoice is sent as a link to pay) or from a prepaid wallet.
3. Open Khalti on the right channel
On the hosted page the customer picks Khalti and, inside it, the wallet, e-banking, mobile banking, connectIPS or SCT. If you build your own payment page against the public checkout endpoints, you can skip Khalti's picker: POST /api/v1/checkouts/{public_id}/pay accepts a channel of KHALTI, EBANKING, MOBILE_BANKING, CONNECT_IPS or SCT, and for the two banking channels a bank id from GET /api/v1/checkouts/{public_id}/khalti/banks?type=ebanking or ?type=mobilecheckout. Bank ids differ between Khalti's sandbox and live, which is why the list is proxied per checkout.
curl https://api.tola.com.np/api/v1/checkouts/chk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6/pay \
-H "Content-Type: application/json" \
-d '{ "provider": "khalti", "channel": "MOBILE_BANKING", "bank": "<idx from the bank list>", "collection_method": "invoice_link" }'
The reply is { "provider": "khalti", "flow": "redirect", "redirect_url": "https://pay.khalti.com/?pidx=…", "payment_intent_id": "…" } (the sandbox host is test-pay.khalti.com). Send the browser there. Calling /pay again with the same provider while the checkout is payment_pending returns the same open intent, so a refresh does not create a second payment. These public endpoints are rate-limited to 60 requests a minute per IP.
4. Return and verification
Khalti sends the customer to /api/v1/checkouts/{id}/return. TolaPay ignores the query string and calls Khalti's lookup for the pidx; only a confirmed payment fulfils the checkout. The customer is then redirected to the hosted page with ?result=completed and on to your success_url, with {CHECKOUT_ID} replaced by the public id. On your success page you may call GET /api/v1/checkouts/{public_id}/status to show the right message, but grant access from the webhook, not from the redirect.
5. Handle invoice.paid
Subscribe an endpoint to invoice.paid (and subscription.created if you want the subscription id as soon as it exists). Each delivery is signed with Tola-Signature, t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. data is the Invoice:
{
"id": "we_b2c3d4e5f6g7h8i9j0k1",
"type": "invoice.paid",
"created_at": "2026-11-13T09:35:02Z",
"organization_id": "org_a1b2c3d4e5f6g7h8i9j0",
"data": {
"id": "inv_b2c3d4e5f6g7h8i9j0k1",
"number": "TOLA-2026-0043",
"customer_id": "cus_q2w8e5r1t7y4u9i3o6p0",
"customer_name": "Chautari Labs",
"customer_email": "finance@chautari.example",
"subscription_id": "sub_z9x8c7v6b5n4m3a2s1d0",
"status": "paid",
"currency": "NPR",
"period_start": "2026-11-13T00:00:00Z",
"period_end": "2026-12-13T00:00:00Z",
"lines": [
{ "kind": "base", "description": "Growth plan — base", "units": 1, "unit_amount_cents": 1500000, "amount_cents": 1500000, "metric_code": null },
{ "kind": "seats", "description": "5 seats × NPR 1,000", "units": 5, "unit_amount_cents": 100000, "amount_cents": 500000, "metric_code": null }
],
"subtotal_cents": 2000000,
"discount_cents": 0,
"credits_cents": 0,
"tax_rate_pct": 13,
"tax_inclusive": false,
"tax_cents": 260000,
"total_cents": 2260000,
"amount_paid_cents": 2260000,
"amount_due_cents": 0,
"payment_status": "succeeded",
"paid_at": "2026-11-13T09:35:01Z",
"pdf_url": "/api/v1/invoices/inv_b2c3d4e5f6g7h8i9j0k1/pdf",
"created_at": "2026-11-13T09:35:01Z"
}
}
Verify the signature, reject deliveries older than five minutes, de-duplicate on the event id (retries come after 1, 5 and 30 minutes, then 2 and 12 hours), then activate the workspace for data.subscription_id and return a 2xx within 10 seconds. To tie it back to the sign-up, keep the checkout id from step 2: GET /api/v1/checkouts/{id} returns subscription_id and invoice_id once the checkout is completed, and payment.succeeded carries checkout_session_id if you prefer a second event over a lookup. The same handler fires for every renewal paid through the invoice link, and for eSewa or card payments too, so you write it once. The webhook handler guide has the details.
Refunds and reconciliation
Khalti has no refund API that TolaPay calls. Refund in the Khalti merchant dashboard and record it with POST /api/v1/payments/{id}/refund and "method": "manual". GET /api/v1/payments/{id} keeps Khalti's own identifiers in provider_payment_id and provider_reference for matching against your Khalti statement.
Next step
Create the checkout above with a tola_test_ key and a sandbox Khalti key, pay it from Khalti's test wallet, and confirm the delivery under Developers → Webhooks. Then drop allowed_providers to offer eSewa and cards next to Khalti; the eSewa guide describes how that rail differs. Live payments are enabled for businesses in the closed pilot; join the waiting list for a pilot code.