NepalOTP Documentation

Getting Started

Authentication

All API requests require authentication via an API key, passed either as an X-API-Key header or as a Bearer token in the Authorization header. Either works identically — pick whichever your HTTP client makes easier.

X-API-Key: npot_live_1a2b3c4d5e6f7g8h9i0j

Authorization: Bearer npot_live_1a2b3c4d5e6f7g8h9i0j

Key rotation

You can have up to 3 active API keys at any time. When rotating keys:

1. Generate a new key in the dashboard
2. Deploy your application with the new key
3. Revoke the old key once migration is complete

Core Concepts

OTP Lifecycle

Server-side generation and verification

OTPs are generated and verified exclusively on NepalOTP servers. Your application never stores OTPs. When a user submits a code, your backend sends it to NepalOTP for verification.

Expiry and attempt limits

Sending an OTP

Generates a new OTP and sends it via SMS to the specified phone number. The OTP message uses a fixed template format.

Request parameters

OTP message format

SMS-only delivery, using this fixed system message — it is not a customizable template. The code and expiry minutes shown here are dynamic, based on your app's configured OTP length (6 digits by default) and expiry time (otp_expiry_seconds, default 300 seconds / 5 minutes).

Example request

curl -X POST https://nepalotp.com/api/v1/otp/send \
  -H "Authorization: Bearer npot_live_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+9779841234567",
    "reference": "user_signup_abc123"
  }'

Success response

{
  "success": true,
  "message": "OTP sent successfully",
  "otp_id": "otp_8f9a7b6c5d4e3f2a",
  "data": {
    "expires_at": "2026-01-15T10:35:00+05:45",
    "expires_in_seconds": 300
  }
}

Common errors

Verifying an OTP

Verifies an OTP submitted by the user. The OTP is invalidated after successful verification or when the maximum attempt limit is reached.

Request parameters

Example request

curl -X POST https://nepalotp.com/api/v1/otp/verify \
  -H "Authorization: Bearer npot_live_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "otp_id": "otp_8f9a7b6c5d4e3f2a",
    "otp": "847293"
  }'

{
  "success": true,
  "message": "OTP verified successfully",
  "data": {
    "phone": "+9779841234567",
    "reference": "user_signup_abc123",
    "verified_at": "2026-01-15T10:32:10+05:45"
  }
}

{
  "success": false,
  "code": "INVALID_OTP",
  "message": "The submitted OTP code is incorrect",
  "data": {
    "attempts_remaining": 2
  }
}

Sandbox Mode

Sandbox mode allows you to integrate and test the NepalOTP API without sending real SMS messages or incurring charges.

Identifying sandbox mode

Sandbox keys belong to apps with the Sandbox environment and are prefixed with npot_test_, while live keys belong to Production apps and use npot_live_. A key's prefix must match its app's environment — using a test key against a production app (or vice versa) is rejected.

Moving to live mode

1. Complete your integration testing in sandbox mode
2. Navigate to Dashboard → Settings → Live Mode
3. Submit a request describing your use case and expected volume
4. Add funds to your wallet once approved
5. Generate a live API key and deploy

Transactional SMS Templates

Transactional SMS templates allow you to send non-OTP messages for specific operational use cases. All templates must be manually approved before use.

Allowed use cases

Template restrictions

• No links or URLs
• No promotional content or offers
• No free-text composition at runtime
• No bulk campaigns (use Bulk SMS API for bulk/promotional campaigns)

Template approval process

1. Submit template via Dashboard → Templates → Create
2. Include template name, content, and use case description
3. Reviewed by AI moderation the moment you submit — most templates are approved or rejected instantly; a genuinely ambiguous template is escalated to manual review, completed within one business day
4. Approved templates receive a template_id

Example template submission

Your order {{order_id}} has been shipped. 
Expected delivery: {{delivery_date}}. 
Thank you for shopping with {{brand_name}}.

Sending a transactional SMS

curl -X POST https://nepalotp.com/api/v1/sms/send \
  -H "Authorization: Bearer npot_live_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+9779841234567",
    "template_id": "tpl_order_shipped",
    "variables": {
      "order_id": "ORD-2024-0847",
      "delivery_date": "Jan 18, 2024",
      "brand_name": "ShopNP"
    }
  }'

Success response

{
  "success": true,
  "message": "SMS sent successfully",
  "sms_id": "sms_8f9a7b6c5d4e3f2a",
  "data": {
    "sent_at": "2026-01-15T10:32:10+05:45"
  }
}

Bulk / Promotional SMS

Bulk SMS sends one free-text message to many recipients in a single call — the promotional/marketing channel, separate from pre-approved transactional templates. No template is required, but every message is screened automatically before anything is charged or sent.

Sending a bulk SMS

curl -X POST https://nepalotp.com/api/v1/sms/bulk-send \
  -H "Authorization: Bearer npot_live_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Get 20% off your next order this weekend only!",
    "mobiles": ["+9779841234567", "+9779801112223"]
  }'

Success response (sent instantly)

{
  "success": true,
  "message": "Bulk SMS sent",
  "batch_id": "bulk_8f9a7b6c5d4e3f2a",
  "data": {
    "recipient_count": 2,
    "sent_count": 2,
    "invalid_count": 0,
    "segments": 1,
    "ntc": 1,
    "ncell": 1,
    "smartcell": 0,
    "invalid_numbers": [],
    "sent_at": "2026-01-15T10:32:10+05:45"
  }
}

Invalid recipients (all-or-nothing)

Our SMS gateway rejects the entire request if even one number in mobiles is invalid or unreachable — it does not partially deliver to the valid numbers. If this happens, nothing is sent to anyone in the batch and you are refunded in full automatically, never charged partially. Validate phone numbers before submitting to avoid this.

{
  "success": false,
  "code": "INVALID_RECIPIENTS",
  "message": "Some numbers in this request are invalid, so nothing was sent to anyone. You have been fully refunded.",
  "batch_id": "bulk_8f9a7b6c5d4e3f2a",
  "data": {
    "invalid_numbers": ["9849059160"]
  }
}

Queued for manual review

{
  "success": true,
  "message": "Content queued for manual review",
  "batch_id": "bulk_8f9a7b6c5d4e3f2a",
  "data": {
    "status": "pending_review",
    "recipient_count": 2,
    "estimated_review_time": "within 1 business day"
  }
}

Check the outcome of a queued batch any time with:

Limits

• Up to 500 recipients per request (mobiles is a JSON array of E.164 numbers)
• Each recipient counts against your app's daily SMS limit
• Invalid numbers reported by the carrier are automatically refunded

Webhooks

Webhooks let you receive real-time delivery and verification updates for OTP and SMS without polling. Configure a webhook URL per app and we will POST signed events whenever activity occurs.

Events

Example payload

{
  "id": "evt_9d8a7c6b5a4f3e2d",
  "event": "otp.sent",
  "created_at": "2026-01-04T16:42:00+05:45",
  "app": {
    "app_id": "app_k2Y9s0XrT3aB",
    "name": "Demo App",
    "environment": "sandbox"
  },
  "data": {
    "otp_id": "otp_8f9a7b6c5d4e3f2a",
    "phone": "+9779812345678",
    "reference": "login-123",
    "status": "sent",
    "is_sandbox": true,
    "cost": "0.0000",
    "expires_at": "2026-01-04T16:47:00+05:45",
    "sent_at": "2026-01-04T16:42:00+05:45"
  }
}

Signature verification

We sign webhook requests when a webhook_secret is set. Verify the signature using the raw request body and the X-Npot-Signature header.

$signature = $_SERVER['HTTP_X_NPOT_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_NPOT_TIMESTAMP'] ?? '';
$payload = file_get_contents('php://input');

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $webhookSecret);
$header = "t={$timestamp},v1={$expected}";

if (! hash_equals($header, $signature)) {
    http_response_code(400);
    exit('Invalid signature');
}

Template Variables & Validation

Template variables allow dynamic content insertion within approved templates. Variables are validated at runtime to ensure message integrity.

Variable syntax

Variables use double curly brace syntax: {{variable_name}}

Naming rules

• Letters, numbers, and underscores (word characters)

Value rules

Template content itself (not the variable values you send at runtime) goes through spam and content review during template approval — see Template restrictions above.

Runtime enforcement

When sending a transactional SMS, the API validates that every variable referenced in the template's content (e.g. {{order_id}}) is present in the variables object and is a string of 500 characters or fewer. Extra keys you send beyond what the template uses are accepted and simply ignored.

Validation error example

{
  "success": false,
  "code": "MISSING_VARIABLES",
  "message": "Missing required variables",
  "data": {
    "missing_variables": ["order_id"]
  }
}

Rate Limits & Abuse Protection

Rate limits are enforced at two levels: a fixed platform-wide throttle on every request, and a per-app business limit on OTP/SMS volume that you configure per phone number when you create the app (and can change any time from Dashboard → Apps → Manage).

Platform-wide request throttle

Applies to every API call regardless of endpoint, before your app's own limits are checked.

OTP rate limits (default, per app)

These are the values a newly created app starts with — every row is configurable.

Transactional SMS limits (default, per app)

Why limits exist

Rate limits prevent SMS bombing attacks against individual phone numbers, protect carrier relationships, and ensure fair usage across all customers.

Rate limit response

{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many OTP requests for this phone number",
  "data": {
    "retry_after": 3600
  }
}

Pricing & Billing

NepalOTP uses a prepaid wallet model. You add funds to your account and usage is deducted in real time.

Prepaid wallet

Add funds via the dashboard using supported payment methods. Your wallet balance is displayed on the dashboard and available via API.

Billing behavior

Message segments

Live SMS (transactional templates and bulk) is billed per segment, not per message — 1 credit per segment, direct pass-through with no markup on length.

A message switches to Unicode the moment it contains any character outside the GSM-7 alphabet — this is all-or-nothing per message, not per character, so a single Nepali word in an otherwise-English message drops the whole message's budget from 160 to 70 characters per segment. Both /v1/sms/send and /v1/sms/bulk-send return a segments field so you always know exactly what a send was billed as.

Errors & Status Codes

All API errors return a consistent structure with an error code and human-readable message.

Error response structure

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "Human readable description",
  "data": {}
}

code, message, and data are always top-level fields — errors are never nested under a separate error object.

Error code reference

Best Practices

FAQ

Support & Contact

When contacting support, include:

• Your account email or organization name
• Request ID from the API response (if applicable)
• Timestamp of the issue
• Error code and message received
• Steps to reproduce the issue