FAST WHATSAPP OTP - API DOCUMENTATION

Complete guide for integrating WhatsApp OTP into your standalone website

OVERVIEW

Fast WhatsApp OTP provides a REST API for sending and verifying OTP codes via WhatsApp. This documentation will help you integrate OTP functionality into your standalone website.

Base URL:

https://otpmore.hirelan.com/api/

AUTHENTICATION

All API requests require authentication using API Key and API Secret. You can get these from your dashboard after logging in.

Headers Required:

HEADER DESCRIPTION EXAMPLE
Authorization Bearer token with your API Key Bearer your_api_key_here
X-API-Secret Your API Secret Key your_api_secret_here
Content-Type Request content type application/json

Security Features:

  • Domain Verification: API keys can be restricted to specific domains
  • API Secret: Additional security layer with secret key
  • Request Origin Check: System automatically checks request origin domain

ENDPOINTS

1. Send OTP

Endpoint: POST https://otpmore.hirelan.com/api/send-otp

Request Body:

{
  "mobile": "919876543210"
}

Success Response (200):

{
  "status": "sent",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "OTP sent successfully",
  "expires_at": "2024-01-01 12:05:00"
}

Error Response (400/401/403):

{
  "error": "Error message here"
}

cURL Example:

curl -X POST https://otpmore.hirelan.com/api/send-otp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"mobile":"919876543210"}'

2. Verify OTP

Endpoint: POST https://otpmore.hirelan.com/api/verify-otp

Request Body:

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "123456"
}

Success Response (200) - Verified:

{
  "status": "verified",
  "message": "OTP verified successfully"
}

Error Response (400) - Invalid/Expired:

{
  "error": "Invalid OTP"
}

Possible errors: "Invalid OTP", "OTP has expired", "Maximum retry attempts exceeded"

cURL Example:

curl -X POST https://otpmore.hirelan.com/api/verify-otp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"550e8400-e29b-41d4-a716-446655440000","otp":"123456"}'

INTEGRATION EXAMPLE

JavaScript Example (Frontend):

// Send OTP
async function sendOTP(mobile) {
  const response = await fetch('https://otpmore.hirelan.com/api/send-otp', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'X-API-Secret': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ mobile: mobile })
  });
  
  const data = await response.json();
  
  if (response.ok) {
    console.log('OTP sent! Transaction ID:', data.transaction_id);
    return data.transaction_id;
  } else {
    console.error('Error:', data.error);
    throw new Error(data.error);
  }
}

// Verify OTP
async function verifyOTP(transactionId, otp) {
  const response = await fetch('https://otpmore.hirelan.com/api/verify-otp', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'X-API-Secret': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      transaction_id: transactionId,
      otp: otp
    })
  });
  
  const data = await response.json();
  
  if (response.ok && data.status === 'verified') {
    console.log('OTP verified successfully!');
    return true;
  } else {
    console.error('Verification failed:', data.error);
    return false;
  }
}

// Usage
const mobile = '919876543210';
sendOTP(mobile).then(transactionId => {
  // Show OTP input form
  const userOTP = prompt('Enter OTP:');
  verifyOTP(transactionId, userOTP).then(verified => {
    if (verified) {
      alert('OTP verified! Proceed with login.');
    } else {
      alert('Invalid OTP. Please try again.');
    }
  });
});

PHP Example (Backend):

// Send OTP
function sendOTP($mobile) {
  $url = 'https://otpmore.hirelan.com/api/send-otp';
  $data = json_encode(['mobile' => $mobile]);
  
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'X-API-Secret: YOUR_API_SECRET',
    'Content-Type: application/json'
  ]);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}

// Verify OTP
function verifyOTP($transactionId, $otp) {
  $url = 'https://otpmore.hirelan.com/api/verify-otp';
  $data = json_encode([
    'transaction_id' => $transactionId,
    'otp' => $otp
  ]);
  
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'X-API-Secret: YOUR_API_SECRET',
    'Content-Type: application/json'
  ]);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  $result = json_decode($response, true);
  return isset($result['status']) && $result['status'] === 'verified';
}

WORKFLOW

  1. User enters mobile number on your website
  2. Your website calls Send OTP API with mobile number
  3. API validates: Domain → API Key → API Secret
  4. OTP is sent to WhatsApp via Meta API
  5. Transaction ID is returned (valid for 2 minutes)
  6. User enters OTP on your website
  7. Your website calls Verify OTP API with transaction ID and OTP
  8. API returns status: "verified" (success) or error message (failed)

ERROR CODES

HTTP CODE ERROR MESSAGE DESCRIPTION
400 Mobile number is required Missing mobile parameter in request
400 Transaction ID and OTP are required Missing parameters in verify request
400 Invalid OTP OTP code doesn't match
400 OTP has expired OTP expired (default: 5 minutes)
400 Maximum retry attempts exceeded Too many failed verification attempts (default: 3)
401 Missing or invalid Authorization header API Key not provided or invalid
401 Invalid API secret API Secret doesn't match
401 Domain not allowed for this API key Request origin domain not in allowed list
403 Insufficient wallet balance User wallet balance is too low

IMPORTANT NOTES

  • ⚠️ Transaction ID expires in 2 minutes - Store it securely and verify quickly
  • ⚠️ OTP expires in 5 minutes - Default expiry time
  • ⚠️ Max 3 retry attempts - After 3 failed attempts, transaction is locked
  • ⚠️ Domain verification - If API key has allowed domains, requests must come from those domains
  • ⚠️ Mobile format - Use country code + number without + (e.g., 919876543210)
  • ⚠️ Never expose API keys - Use environment variables or secure storage

GET API CREDENTIALS

To get your API Key and API Secret:

  1. Log in to your Fast WhatsApp OTP dashboard
  2. Navigate to API Keys section
  3. Create a new API key (you'll get both Key and Secret)
  4. Copy both credentials immediately (they won't be shown again)
  5. Optionally set allowed domains for additional security