KYC & wallet limits

Trile operates within Nepal Rastra Bank (NRB) rules. The most important consequence for your integration is that wallets have caps tied to the customer’s KYC tier.

KYC tiers and caps

Each customer has a KYC tier that sets a maximum wallet balance and per-transaction/top-up limits. A customer raises their tier by submitting more verification.

• Read the current state from GET /v1/wallet/balance (end-user session): kyc_tier, cap_paisa, kyc_status.
• Submit/raise KYC via POST /v1/wallet/kyc; check status with GET /v1/wallet/kyc (returns not_submitted if none on file).

The exact caps per tier are set by NRB policy and configured server-side — read cap_paisa rather than hard-coding a number.

Errors you’ll encounter

Code	When	What to do
wallet_cap_exceeded	A top-up would push the balance over cap_paisa.	Show the cap; suggest a smaller top-up or a KYC upgrade.
onboarding_incomplete	Merchant (your) onboarding/KYC isn’t finished.	Finish onboarding in the merchant dashboard before going live.

What this means for your UX

• Surface the cap. Before a top-up, show balance_paisa and cap_paisa so the customer knows their headroom.
• Offer the KYC upgrade path when a customer hits the cap and needs a higher limit.
• Expect partial funding. A customer on a low tier may not be able to hold enough to cover an expensive plan’s first cycle — guide them to upgrade KYC first.

Data localization

NRB also requires data to remain in Nepal. That’s an operational/hosting concern (Trile deploys to a Nepal-eligible host) and doesn’t change the API surface — but it’s why these docs and the platform are designed to be self-hostable rather than tied to a foreign SaaS.