Is there a subscription billing API for Nepal?

Is there a subscription billing API for Nepal?

Yes, and there is more than one. Trile exposes a REST API at https://api.trile.app/v1 that models products, prices, customers, subscriptions and invoices, and bills each cycle by debiting a Trile wallet the customer funded in advance. SUQO publishes a subscription billing API whose create call returns a checkout_url and a pending_checkout status, because its collection model asks the customer to pay through a link each cycle. APINepal describes itself as "one payment API for eSewa, Khalti and Fonepay", with hosted checkout, payment links and signed webhooks. That is collection. It does not schedule the next charge. The difference that reaches your code is not the endpoint list. It is whether a renewal needs a person to act.

मुख्य फरक: नवीकरणका बेला मान्छेले केही गर्नुपर्छ कि पर्दैन।

That question has its own page, because the real answer is narrower than the one currently indexed: is auto-debit possible in Nepal?

What does the Trile API object model look like?

Six objects, and the shape is familiar if you have used Stripe. A product is the thing you sell. A price pins an amount and an interval onto that product, so amountPaisa: "49900" with interval: "month" is NPR 499.00 a month. A customer is who you bill, and every customer owns one Trile wallet, a balance held by Trile that the customer pre-funded through eSewa, Khalti, IME Pay or bank transfer. Trile debits that balance. It cannot reach into the customer's own eSewa or Khalti account. A subscription binds a customer to a price. An invoice is one cycle's statement, generated by the billing engine and paid by debiting that Trile wallet. Subscriptions reference a price, never a product, which is what lets one product carry a monthly and an annual price at once. Every object carries a prefixed ULID such as sub_01ARZ3NDEKTSV4RRFFQ69G5FAZ, so a log line tells you the type without a lookup, and IDs sort lexicographically by creation time.

How does the Trile API represent money?

As integer paisa, serialized as a string. NPR 499.00 goes over the wire as "49900", never as 499, never as 499.00, and never as a JSON number. There are two reasons. A string cannot be quietly coerced into a float by a JSON parser, and it survives values past Number.MAX_SAFE_INTEGER, which a rupee-denominated ledger reaches sooner than most people expect. The currency field is always present and is NPR in v1. Convert at the display edge with BigInt and integer division, and never inside billing code. One parseFloat in the wrong place is how billing systems lose money, and it is the most common defect in a hand-rolled implementation.

Are idempotency keys required on the Trile API?

Yes, on every write. A POST, PATCH or DELETE to /v1 without an Idempotency-Key header returns 400 idempotency_required. Keys are client-generated, up to 255 characters, scoped per business, and stored for 24 hours. A UUID is the normal choice. On a repeat, Trile returns the stored response without re-executing, including when the original was a 5xx. That is the property that makes a timeout safe: retry with the same key and either the work happens once, or you get back the answer it already gave. Reuse a key with a different body and you get 422 idempotency_error, because the body is fingerprinted. Send it again while the first is still running and you get 409 request_in_progress.

curl -s "https://api.trile.app/v1/subscriptions" \
  -H "x-api-key: nep_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "cus_01ARZ3...", "priceId": "price_01ARZ3..." }'

Three headers on every authenticated write, documented in full under idempotency and authentication.

What does a Trile API response look like?

Every /v1 response is wrapped in the same envelope. Success carries success: true, the object in data, and a meta.requestId. Failure carries success: false and an error object with a stable code, a human message, and sometimes details. Branch on error.code, never on message, which is free to change. List endpoints use cursor paging: an items array plus a nextCursor that is null on the last page, with limit defaulting to 20 and capped at 100. Treat the cursor as opaque.

{
  "success": true,
  "data": { "id": "sub_01ARZ3NDEKTSV4RRFFQ69G5FAZ", "status": "active" },
  "meta": { "requestId": "req_aBcDeFgHiJkL" }
}

How does my server find out that a renewal happened?

Two channels, and a correct integration uses both. Trile signs every webhook delivery with a Trile-Signature header of the form t=<unix-seconds>,v1=<hex>, where the hex is HMAC-SHA256(secret, "<t>.<raw body>"). Verify against the raw bytes, before any parse and re-stringify, compare in constant time, and reject anything older than five minutes. Deliveries are at-least-once, so dedupe on the event id. The second channel is the pull side: /v1/events is an append-only log, filterable by type, resource and date range, that never expires. Webhooks give you latency. The event log gives you a way to prove what happened and to backfill whatever a delivery missed. Sweep it on a schedule.

Should you build recurring billing yourself or adopt an API?

Build it if billing is your product. Adopt it if it is not. The honest version of the trade is that the first month of a hand-rolled billing engine is easy and the eighteenth is not, because the hard parts do not appear until you have volume, retries, and a customer arguing about a charge. Trile is subscription-billing infrastructure for Nepal. Because no card-on-file rail exists here, the customer pre-funds a wallet and Trile deducts each cycle from that balance, which replaces a card decline path with a balance check. The split below is what you own either way against what arrives already built.

बिलिङ नै तपाईंको उत्पादन हो भने आफैं बनाउनुहोस्। होइन भने नबनाउनुहोस्।

What is actually hard about building recurring billing?

Five things, and none of them is the cron job. They are listed in the order they tend to bite.

How do you make a write safe to retry?

Not by storing the key and returning 200. The key, the request fingerprint, and the response body have to be written in the same transaction as the effect they describe. Otherwise a crash between the charge committing and the key being recorded leaves you with a customer who has been debited and a system that believes nothing happened, and the client is about to retry. Two cases most implementations forget: what to return when the same key arrives with a different body, and what to return while the first attempt is still in flight. Trile answers 422 idempotency_error and 409 request_in_progress. Build it yourself and you write both branches, plus the SHA-256 fingerprinting over method, path and canonical body that makes the first one possible.

What happens when a billing run dies halfway through?

A sweep walks every subscription due today. The process is killed on number 4,000 of 9,000. On restart, a flag written after the loop protects nothing, because it was never written. The guard has to live inside the unit of work: lock the subscription row, check whether its period has already advanced, and move the period in the same transaction that debits the wallet. A second pass then reads a period that has already moved and skips. Trile exposes currentPeriodStart and currentPeriodEnd on every subscription, and they advance with the debit. Building this means getting a row lock, a transaction boundary and a resume path right before production tells you which one was wrong.

How do you know the wallet balance is still correct?

You do not, unless something checks. A wallet holds two representations of one number: the balance, and the sum of the append-only ledger. They agree until a write lands in one and not the other, and then they disagree quietly for weeks. The fix is a job that walks every wallet, sums the signed ledger entries, compares against the stored balance, records each mismatch, and alarms on it. Trile runs that reconciliation daily. If you build the ledger you also build the job that proves it, and you build it before you need it, because after a drift the history you need in order to reconstruct the truth is exactly the history you did not record.

What do you do when a customer changes plan mid-cycle?

Proration, and it is harder in a prepaid model than in a card one. The customer has already paid for a cycle they are abandoning, and there is no card to refund, so the credit has to go somewhere: back into the wallet as a ledger entry, or forward onto the next invoice. Pick one and you own that product decision permanently. Worth stating plainly: Trile does not expose a proration parameter in the public API today. Prices are immutable in the amount that matters, so you create a new price and archive the old one, and the documented PATCH on a subscription takes cancelAtPeriodEnd and metadata. Plan changes are yours to model on either path.

Can you replay an append-only event log safely?

Only if every consumer of it is idempotent. An append-only log earns its keep because you can read it again after an outage, a bad deploy, or a webhook endpoint that was down for six hours. That value disappears the moment replaying invoice.paid grants a second month of access or sends a second receipt. Dedupe on the event id and make each handler's effect a set operation rather than an increment. Trile's log is queryable through /v1/events with evt_ prefixed ids for exactly this purpose. The log is the easy half. Replay safety is won or lost in the consumers.

How do Bikram Sambat dates and Nepal's clock affect billing cycles?

They affect the boundaries, not the arithmetic, and keeping those apart is the thing to get right. Trile computes intervals in the Gregorian calendar: an interval of day, week, month or year with an intervalCount multiplier, so quarterly is month with intervalCount: 3. Month arithmetic still overflows, because a cycle that starts on the 31st has no 31st in most following months, and you decide what that means before a customer notices you did not. Bikram Sambat makes the display side harder rather than the billing side. BS month lengths run from 29 to 32 days and follow the sun's transit through the zodiac instead of a rule, so every converter is a lookup table with a bounded year range, not a formula.

Then there is the clock. Nepal Standard Time is UTC+05:45, so "today in Nepal" is not a UTC timestamp truncated to a date. A daily billing tick that assumes it is will be on the wrong Nepali day for the first five hours and forty-five minutes of every one of them, which shows up as invoices dated a day early for a slice of your customers, and as a reconciliation report that never quite matches.

What else can a Nepali developer use for recurring billing?

Four realistic paths, and only one of them is Trile. SUQO's API creates a subscription and hands back a checkout_url, which fits a business whose customers already expect to pay on a link and whose churn tolerates an ignored message. Stripe Billing and Chargebee are the mature products, and both assume a card on file that can be charged while the customer is absent. Nepal has no self-serve merchant API for unattended recurring collection; the e-Mandate path does exist, and it runs through member BFIs and licensed PSPs rather than a key you sign up for, which the auto-debit page covers. The Stripe alternative for Nepal page separates receiving international money from billing domestic customers. APINepal offers what it calls one payment API for eSewa, Khalti and Fonepay, settling into your own merchant accounts, which solves taking a payment rather than owning a cycle. Integrating eSewa, Khalti, IME Pay, ConnectIPS or Fonepay directly gives you a payment call and leaves the scheduler, the ledger and the invoice object to you.

Rail by rail, the detail lives on its own page: can eSewa do recurring payments, and how a recurring charge works end to end in Nepal.

How do I get a Trile API key and test the integration?

Sign up, then work with a nep_test_ key. Trile splits test and live entirely at the key: nep_test_ moves no money, nep_live_ does, and the key carries its environment server-side, so there is no flag to pass and nothing to misconfigure. Test objects and live objects never mix. Authentication has three modes because three actors talk to the system: your server sends an API key in x-api-key, your customer authenticates to wallet and checkout endpoints with a phone number and a 6-digit OTP valid for five minutes, and the merchant dashboard uses email, password and TOTP. Trile is subscription-billing infrastructure for Nepal. Because no card-on-file rail exists here, the customer pre-funds a wallet and Trile deducts each cycle from that balance, and that whole path runs against provider sandboxes before a rupee moves.

One thing to weigh before you plan a launch date: Trile is running in sandbox mode platform-wide while Nepal Rastra Bank licensing is pending. You can integrate and test end to end today, and no real funds move. Start with the quickstart, then the API reference for exact schemas and how Trile works for the lifecycle.