Payments · Guides
Create a payment link in Nepal
Make a reusable payment link that takes Khalti, eSewa and cards, share it in WhatsApp or as a printed QR, and confirm each payment from a signed invoice.paid webhook. With the API call, the response and the webhook.
- Written by
- TolaPay team
- Published
- Reading time
- 5 min read
A payment link is a URL that opens a checkout for a product or plan, every time, for anyone. In Nepal that is how a lot of selling happens: a price agreed in a WhatsApp thread, a link sent back, a Khalti or eSewa payment a minute later. TolaPay's checkout links do that with your own merchant accounts behind them and a webhook when money arrives. The payment links page has the overview; the payment gateway for Nepal page covers the rails. This guide is the how-to.
No code: the dashboard
Every plan and product has a default link. In the dashboard, open the plan or product and choose Copy link. That calls POST /api/v1/plans/{id}/checkout_link (or /products/{id}/checkout_link) under the hood, creating the default link the first time and returning the same one after that. Paste the URL into a chat or email. The hosted page the link opens also shows a QR of itself, so a screenshot of it works on a poster or a counter.
With the API: a link for a campaign
Build a link yourself when you want a preset discount, specific rails, a usage limit or an expiry. items needs at least one entry, each with either an active plan_id or a product_id that has a one-time price. A link can offer several items and the buyer switches between them on the page.
curl https://api.tola.com.np/api/v1/checkout_links \
-H "Authorization: Bearer $TOLA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: link-dashain-2026" \
-d '{
"label": "Dashain campaign — yearly plan",
"items": [{ "plan_id": "plan_g4wv8t2kq6m1xr9zb3dn" }],
"seats_default": 1,
"seats_locked": true,
"allowed_providers": ["khalti", "esewa"],
"allow_discount_codes": true,
"require_phone": true,
"max_uses": 200,
"expires_at": "2026-11-30T18:15:00Z",
"success_url": "https://chautari.example/thanks?checkout={CHECKOUT_ID}",
"metadata": { "campaign": "dashain-2026" }
}'
allowed_providers left empty means every connected rail. max_uses counts completed checkouts, not visits. require_phone makes the buyer enter a number before paying, which you will want for anything delivered by SMS or Viber.
The response
201 Created with the link:
{
"id": "cl_a1b2c3d4e5f6g7h8i9j0",
"secret": "tcl_k3j5h7g9f2d4s6a8q1w3e5r7t9y2u4i6o8p1z3",
"url": "https://app.tola.com.np/l/tcl_k3j5h7g9f2d4s6a8q1w3e5r7t9y2u4i6o8p1z3",
"embed_html": "<a href=\"https://app.tola.com.np/l/tcl_k3j5h7g9f2d4s6a8q1w3e5r7t9y2u4i6o8p1z3\" data-tola-checkout>Buy</a>",
"label": "Dashain campaign — yearly plan",
"items": [{ "plan_id": "plan_g4wv8t2kq6m1xr9zb3dn" }],
"seats_default": 1,
"seats_locked": true,
"allowed_providers": ["khalti", "esewa"],
"discount_id": null,
"allow_discount_codes": true,
"require_phone": true,
"success_url": "https://chautari.example/thanks?checkout={CHECKOUT_ID}",
"cancel_url": "",
"metadata": { "campaign": "dashain-2026" },
"max_uses": 200,
"uses": 0,
"clicks": 0,
"checkouts_created": 0,
"completed": 0,
"expires_at": "2026-11-30T18:15:00Z",
"status": "active",
"is_default": false,
"created_at": "2026-11-13T09:30:00Z"
}
Share url. The tcl_… secret in it is the public identifier, so treat the link like a price tag, not a password: anyone with it can start a checkout, and that is the point. embed_html is the same link marked up for the tola.js overlay, which opens checkout over your own page.
What a visit does
Each visit to /l/{secret} mints a fresh checkout from the link and redirects to /c/{public_id}, so every buyer gets their own checkout and their own invoice. A visitor who comes back within 24 hours resumes their pending checkout rather than starting another. The link accepts prefill parameters: ?email=, ?name=, ?phone=, ?plan_id= or ?product_id= to preselect an item, ?discount_code= when the link allows codes, and ?reference_id= which lands in the checkout's metadata as prefill.reference_id. Invalid values are dropped silently; utm_* parameters are kept as prefill.utm_*.
https://app.tola.com.np/l/tcl_k3j5h7g9f2d4s6a8q1w3e5r7t9y2u4i6o8p1z3?email=sita@example.com.np&reference_id=WA-2211
On the checkout page the buyer picks Khalti, eSewa or a card. TolaPay verifies with the rail (Khalti's lookup, eSewa's signed response, Stripe's webhook), creates the customer and subscription if needed, issues the invoice, and returns them to success_url with {CHECKOUT_ID} filled in.
Handle invoice.paid
You will not be watching the dashboard when a link is paid at 11 pm, so subscribe a webhook endpoint to invoice.paid. Deliveries carry Tola-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>) and Tola-Event. data is the Invoice:
{
"id": "we_c3d4e5f6g7h8i9j0k1l2",
"type": "invoice.paid",
"created_at": "2026-11-13T17:05:40Z",
"organization_id": "org_a1b2c3d4e5f6g7h8i9j0",
"data": {
"id": "inv_c3d4e5f6g7h8i9j0k1l2",
"number": "TOLA-2026-0044",
"customer_id": "cus_x1c2v3b4n5m6a7s8d9f0",
"customer_name": "Sita Gurung",
"customer_email": "sita@example.com.np",
"subscription_id": "sub_p0o9i8u7y6t5r4e3w2q1",
"status": "paid",
"currency": "NPR",
"lines": [
{ "kind": "base", "description": "Growth plan — yearly", "units": 1, "unit_amount_cents": 15000000, "amount_cents": 15000000, "metric_code": null }
],
"subtotal_cents": 15000000,
"discount_cents": 3000000,
"credits_cents": 0,
"tax_rate_pct": 13,
"tax_inclusive": false,
"tax_cents": 1560000,
"total_cents": 13560000,
"amount_paid_cents": 13560000,
"amount_due_cents": 0,
"payment_status": "succeeded",
"paid_at": "2026-11-13T17:05:39Z",
"pdf_url": "/api/v1/invoices/inv_c3d4e5f6g7h8i9j0k1l2/pdf",
"created_at": "2026-11-13T17:05:39Z"
}
}
Verify the signature, ignore event ids you have seen (retries come after 1, 5 and 30 minutes, then 2 and 12 hours), deliver, and answer with a 2xx within 10 seconds. The invoice does not carry the link or the prefilled reference. To get them, subscribe to payment.succeeded too: its Payment has checkout_session_id, and GET /api/v1/checkouts/{id} with that id returns the admin object with link_id and metadata, including prefill.reference_id from the URL. The webhook handler guide walks through a handler.
Tracking and switching off
GET /api/v1/checkout_links/{id}/stats returns uses, completed, conversion_pct and revenue_cents for the link. PATCH it to change the discount, the limit or the expiry; DELETE archives it, after which visitors see a 410 page and the link's checkouts and stats are kept.
Next step
Create a link in test mode, open it on your phone, and pay it with a sandbox Khalti or eSewa account; then check the delivery under Developers → Webhooks. For a checkout tied to one specific order rather than a reusable link, create it directly with POST /api/v1/checkouts as the eSewa and Khalti guides show. Live payments are enabled for businesses in the closed pilot; join the waiting list for a pilot code.