NepalOTP Documentation

Getting Started

Authentication

All API requests require authentication via an API key passed in the Authorization header.

Authorization: Bearer notp_live_sk_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

Fixed OTP template

Example request

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

Success response

{
  "success": true,
  "data": {
    "otp_id": "otp_8f9a7b6c5d4e3f2a",
    "phone": "9841234567",
    "expires_at": "2024-01-15T10:35:00Z",
    "attempts_remaining": 3
  }
}

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://api.nepalotp.com/v1/otp/verify \
  -H "Authorization: Bearer notp_live_sk_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "otp_id": "otp_8f9a7b6c5d4e3f2a",
    "code": "847293"
  }'

{
  "success": true,
  "data": {
    "verified": true,
    "phone": "9841234567"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_OTP",
    "message": "The code is incorrect",
    "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 API keys are prefixed with notp_sandbox_ while live keys use notp_live_.

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

Template approval process

1. Submit template via Dashboard → Templates → Create
2. Include template name, content, and use case description
3. Review takes 1-2 business days
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://api.nepalotp.com/v1/sms/send \
  -H "Authorization: Bearer notp_live_sk_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "9841234567",
    "template_id": "tpl_order_shipped",
    "variables": {
      "order_id": "ORD-2024-0847",
      "delivery_date": "Jan 18, 2024",
      "brand_name": "ShopNP"
    }
  }'

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

• Lowercase letters, numbers, and underscores only
• Must start with a letter
• Maximum 32 characters

Value rules

Runtime enforcement

When sending a transactional SMS, the API validates that:

• All required variables are provided
• No extra variables are included
• Values conform to length and character rules

Validation error examples

{
  "success": false,
  "error": {
    "code": "MISSING_VARIABLE",
    "message": "Required variable 'order_id' is missing"
  }
}

{
  "success": false,
  "error": {
    "code": "UNKNOWN_VARIABLE",
    "message": "Variable 'promo_code' is not defined in template"
  }
}

Rate Limits & Abuse Protection

Rate limits protect the platform and end users from abuse. Limits are enforced at multiple levels.

OTP rate limits

Transactional SMS limits

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,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many OTP requests for this phone number",
    "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

Errors & Status Codes

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

Error response structure

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

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