Developer Guide: Implementing Infobip OTP/2FA in Next.js with Node.js

[User's Browser: Frontend UI] <---> [Next.js Server: API Routes] <---> [Infobip API]
  (Enter Phone #) -----------> /api/send-otp ------------> (Send OTP Request)
                                                        <------------ (pinId)
                    <----------- (pinId received)
  (Receive SMS_ Enter OTP) ---> /api/verify-otp ---------> (Verify OTP Request)
                               (with pinId & OTP)       <------------ (Verification Result)
                    <----------- (Success/Failure)

npx create-next-app@latest infobip-otp-nextjs
# Follow the prompts (e.g._ choose TypeScript if desired_ App Router or Pages Router)
cd infobip-otp-nextjs

npm install infobip-api-nodejs-sdk
# or
yarn add infobip-api-nodejs-sdk

# .env.local

# --- IMPORTANT ---
# The values below are placeholders. You MUST replace them with your actual
# credentials and configuration IDs obtained from your Infobip account.
# Failure to do so will prevent the integration from working.
# --- IMPORTANT ---

# Obtain from Infobip Portal (Homepage -> API Base URL for your region)
INFOBIP_BASE_URL=your_infobip_base_url

# Obtain from Infobip Portal (API Key Management)
INFOBIP_API_KEY=your_infobip_api_key

# These will be obtained after configuring the 2FA Application and Message Template in Infobip
INFOBIP_2FA_APP_ID=your_2fa_application_id
INFOBIP_2FA_MESSAGE_ID=your_2fa_message_template_id

infobip-otp-nextjs/
├── lib/
│   └── infobip.js          # Utility for Infobip client initialization
├── pages/
│   ├── api/
│   │   ├── send-otp.js       # API route to send OTP
│   │   └── verify-otp.js     # API route to verify OTP
│   ├── _app.js
│   └── index.js            # Frontend page for OTP interaction
├── public/
├── styles/
├── .env.local              # Your secret credentials
├── package.json
└── node_modules/

// lib/infobip.js
import { Infobip } from ""infobip-api-nodejs-sdk"";

let infobipInstance = null;

export const getInfobipClient = () => {
  if (!infobipInstance) {
    if (!process.env.INFOBIP_BASE_URL || !process.env.INFOBIP_API_KEY) {
      throw new Error(""Infobip Base URL or API Key is missing in environment variables."");
    }
    infobipInstance = new Infobip({
      baseUrl: process.env.INFOBIP_BASE_URL,
      apiKey: process.env.INFOBIP_API_KEY,
      // Optional: Add other configurations like application ID if needed globally,
      // but often better to pass them per request.
    });
  }
  return infobipInstance;
};

// Note on Singletons and Serverless Environments:
// This singleton pattern works well for typical Next.js server deployments.
// However, in serverless environments (like Vercel Serverless Functions),
// the lifecycle might lead to multiple instances or unexpected state retention
// across invocations if not managed carefully. For simple use cases like this,
// it's often acceptable, but be mindful of potential scaling or state issues
// in complex serverless scenarios. Consider initializing the client per-request
// if necessary, though this might have a slight performance overhead.

// pages/api/send-otp.js
import { getInfobipClient } from ""../../lib/infobip"";
// Consider using a robust phone number validation library for production
// import { parsePhoneNumberFromString } from 'libphonenumber-js';

// Placeholder for a structured logger (replace console calls in production)
// import logger from '../../lib/logger'; // Example: Your logger setup

export default async function handler(req, res) {
  if (req.method !== ""POST"") {
    res.setHeader(""Allow"", [""POST""]);
    return res.status(405).json({ message: `Method ${req.method} Not Allowed` });
  }

  const { phoneNumber } = req.body;

  // --- Phone Number Validation ---
  // Basic Regex (Insecure for Production): Allows 10-15 digits. Doesn't validate country codes.
  const basicPhoneNumberRegex = /^\d{10,15}$/;
  if (!phoneNumber || !basicPhoneNumberRegex.test(phoneNumber)) {
    // Production Recommendation: Use a library like libphonenumber-js
    // const parsedNumber = parsePhoneNumberFromString(phoneNumber); // Requires country code usually
    // if (!parsedNumber || !parsedNumber.isValid()) {
    //    return res.status(400).json({ message: ""Valid E.164 phone number format required (e.g., +14155552671)."" });
    // }
    // Using basic validation for this example:
    return res.status(400).json({ message: ""Valid phone number is required (10-15 digits, include country code)."" });
  }
  // --- End Phone Number Validation ---


  if (!process.env.INFOBIP_2FA_APP_ID || !process.env.INFOBIP_2FA_MESSAGE_ID) {
      // logger.error(""Server configuration error: Infobip App ID or Message ID missing.""); // Use logger
      console.error(""Server configuration error: Infobip App ID or Message ID missing."");
      return res.status(500).json({ message: ""Server configuration error."" });
  }

  try {
    const infobip = getInfobipClient();

    // logger.info(`Attempting to send OTP to ${phoneNumber}`); // Use logger
    const response = await infobip.channels.sms.sendTfaPin({
      applicationId: process.env.INFOBIP_2FA_APP_ID,
      messageId: process.env.INFOBIP_2FA_MESSAGE_ID,
      // 'from' can often be omitted if defined in the template or account defaults
      // from: ""YourSenderID"",
      to: phoneNumber, // Assumes phoneNumber includes country code from input
      // Optional: Define placeholder values if your template uses them beyond {{pin}}
      // placeholders: { ""firstName"": ""User"" }
    });

    // Successfully initiated OTP send
    // logger.info({ msg: ""Infobip Send OTP Response OK"", pinId: response.data.pinId }); // Use logger
    console.log(""Infobip Send OTP Response:"", response.data); // Basic logging

    // IMPORTANT: Return the pinId to the client for the verification step
    return res.status(200).json({ pinId: response.data.pinId });

  } catch (error) {
    const errorData = error.response ? error.response.data : error.message;
    // logger.error({ msg: ""Error sending OTP via Infobip"", error: errorData }); // Use logger
    console.error(""Error sending OTP via Infobip:"", errorData); // Basic logging

    // Provide a generic error to the client, log specifics server-side
    let statusCode = 500;
    let message = ""Failed to send OTP."";

    // Handle specific Infobip error codes if needed
    if (error.response && error.response.data && error.response.data.requestError) {
        const serviceException = error.response.data.requestError.serviceException;
        if (serviceException) {
            message = serviceException.text || message;
            // You could map specific messageIds (like rate limits) to 429 status
            if (serviceException.messageId === 'TOO_MANY_REQUESTS') {
                statusCode = 429;
            }
            // Add other specific error mappings if desired
        }
    } else if (error.response && error.response.status) {
        statusCode = error.response.status; // Use status from Infobip if available
    }

    return res.status(statusCode).json({ message });
  }
}

// pages/api/verify-otp.js
import { getInfobipClient } from ""../../lib/infobip"";

// Placeholder for a structured logger (replace console calls in production)
// import logger from '../../lib/logger'; // Example: Your logger setup

export default async function handler(req, res) {
  if (req.method !== ""POST"") {
    res.setHeader(""Allow"", [""POST""]);
    return res.status(405).json({ message: `Method ${req.method} Not Allowed` });
  }

  const { pinId, pin } = req.body;

  // --- Input Validation ---
  if (!pinId) {
    return res.status(400).json({ message: ""Pin ID is required."" });
  }

  // PIN Validation:
  // The regex below assumes a PIN length between 4 and 10 digits.
  // Ideally, this should match the 'PIN Length' configured in your
  // Infobip 2FA Message Template (Section 2.3).
  // Consider making this dynamic or ensuring it matches your config.
  const pinRegex = /^\d{4,10}$/; // Example: Adjust '4' and '10' to match your template's PIN length
  if (!pin || !pinRegex.test(pin)) {
    return res.status(400).json({ message: ""Valid PIN format required."" });
  }
  // --- End Input Validation ---

  try {
    const infobip = getInfobipClient();

    // logger.info(`Attempting to verify OTP for pinId: ${pinId}`); // Use logger
    const response = await infobip.channels.sms.verifyTfaPin(pinId, {
        pin: pin
    });

    // logger.info({ msg: ""Infobip Verify OTP Response OK"", pinId: pinId, verified: response.data.verified }); // Use logger
    console.log(""Infobip Verify OTP Response:"", response.data); // Basic logging

    if (response.data.verified) {
      // OTP Verified Successfully!
      // Perform actions here: e.g., log user in, complete registration, update database flag
      // logger.info(`OTP verification successful for pinId: ${pinId}`); // Use logger
      return res.status(200).json({ verified: true, message: ""OTP verified successfully."" });
    } else {
      // OTP Incorrect or Expired (or other non-verified state)
      // Note: Infobip might return a 200 OK with verified: false for incorrect PINs
      // within the attempt limit. Errors (4xx/5xx) usually indicate other issues.
      // logger.warn(`OTP verification failed for pinId: ${pinId} - Not verified by Infobip.`); // Use logger
      return res.status(400).json({ verified: false, message: ""Invalid or expired OTP."" });
    }

  } catch (error) {
    const errorData = error.response ? error.response.data : error.message;
    // logger.error({ msg: ""Error verifying OTP via Infobip"", pinId: pinId, error: errorData }); // Use logger
    console.error(""Error verifying OTP via Infobip:"", errorData); // Basic logging

    let statusCode = 500;
    let message = ""Failed to verify OTP."";
    let verified = false;

    // Check for specific verification errors (e.g., wrong PIN, expired, max attempts)
    if (error.response && error.response.data && error.response.data.requestError) {
        const serviceException = error.response.data.requestError.serviceException;
         if (serviceException) {
            message = serviceException.text || message; // Use Infobip's error text
            // Map specific errors if needed, e.g., differentiate between wrong PIN and expired PIN
            if (serviceException.messageId === 'PIN_NOT_FOUND') {
                 message = 'OTP session not found or expired.';
                 statusCode = 404; // Not Found is appropriate here
            } else if (serviceException.messageId === 'WRONG_PIN') {
                 message = 'Invalid OTP provided.';
                 statusCode = 400; // Bad Request (client error)
            } else if (serviceException.messageId === 'MAX_ATTEMPTS_EXCEEDED') {
                message = 'Maximum verification attempts reached.';
                statusCode = 429; // Too Many Requests
            } else {
                // Use Infobip's status code if available and seems appropriate
                 statusCode = error.response.status >= 400 ? error.response.status : 400;
            }
         }
    } else if (error.response && error.response.status) {
        statusCode = error.response.status;
    }


    return res.status(statusCode).json({ verified, message });
  }
}

// pages/index.js
import React, { useState } from 'react';

// Frontend Styling Note:
// This example uses basic inline styles (`style={{ ... }}`) for simplicity.
// For production applications, it's highly recommended to use more maintainable
// styling solutions like CSS Modules, Tailwind CSS, styled-components, or Emotion,
// which integrate well with Next.js.

export default function OtpPage() {
  const [phoneNumber, setPhoneNumber] = useState('');
  const [pinId, setPinId] = useState(''); // State to hold the pinId from the backend
  const [otp, setOtp] = useState('');
  const [message, setMessage] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const [isOtpSent, setIsOtpSent] = useState(false); // Controls which form part is shown
  const [isVerified, setIsVerified] = useState(false); // Controls final success message

  const handleSendOtp = async (e) => {
    e.preventDefault();
    setMessage('');
    setIsLoading(true);
    setIsVerified(false);
    setIsOtpSent(false); // Reset OTP state
    setPinId('');       // Reset pinId

    // Frontend Input Consideration:
    // While backend validation is essential, consider adding basic frontend
    // format masking (e.g., using react-imask) or validation for the phone number
    // input to improve user experience and reduce invalid submissions.

    try {
      const res = await fetch('/api/send-otp', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ phoneNumber }),
      });

      const data = await res.json();

      if (res.ok) {
        setPinId(data.pinId); // Store the pinId received from the API
        setIsOtpSent(true);
        setMessage('OTP sent successfully! Please check your phone.');
      } else {
        setMessage(`Error: ${data.message || 'Failed to send OTP'}`);
        setIsOtpSent(false);
      }
    } catch (error) {
      console.error(""Frontend Error Sending OTP:"", error);
      setMessage('An unexpected error occurred. Please try again.');
      setIsOtpSent(false);
    } finally {
      setIsLoading(false);
    }
  };

  const handleVerifyOtp = async (e) => {
    e.preventDefault();
    setMessage('');
    setIsLoading(true);

    try {
      const res = await fetch('/api/verify-otp', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ pinId, pin: otp }), // Send pinId and the entered OTP
      });

      const data = await res.json();

      if (res.ok && data.verified) {
        setIsVerified(true);
        setMessage('Success! Phone number verified.');
        // Optionally reset the form or navigate the user
        setPinId('');
        setOtp('');
        setIsOtpSent(false); // Go back to phone number input stage for next time
        // setPhoneNumber(''); // Optional: clear phone number too
      } else {
        // Handle verification failure (invalid OTP, expired, etc.)
        setMessage(`Error: ${data.message || 'Failed to verify OTP'}`);
        setIsVerified(false);
        setOtp(''); // Clear OTP input field for retry attempt
      }
    } catch (error) {
       console.error(""Frontend Error Verifying OTP:"", error);
      setMessage('An unexpected error occurred during verification.');
      setIsVerified(false);
    } finally {
      setIsLoading(false);
    }
  };

  // Handler for the ""Change/Resend"" button
  const handleResetFlow = () => {
    setIsOtpSent(false); // Go back to the phone number input stage
    setMessage('');
    setOtp('');
    setPinId('');
    setIsVerified(false);
    // The phone number input remains populated, allowing easy resend or correction.
  };


  return (
    <div style={{ maxWidth: '400px'_ margin: '50px auto'_ padding: '20px'_ border: '1px solid #ccc'_ borderRadius: '8px' }}&gt;
      <h1&gt;Phone Verification</h1&gt;

      {/* Show forms only if not successfully verified */}
      {!isVerified && (
        <form onSubmit={!isOtpSent ? handleSendOtp : handleVerifyOtp}&gt;
          {!isOtpSent ? (
            // Stage 1: Enter Phone Number
            <>
              <label htmlFor=""phoneNumber"" style={{ display: 'block'_ marginBottom: '5px' }}&gt;Phone Number:</label&gt;
              <input
                type=""tel"" // Use ""tel"" type for better mobile UX
                id=""phoneNumber""
                value={phoneNumber}
                onChange={(e) =&gt; setPhoneNumber(e.target.value)}
                placeholder=""e.g., +14155552671 (with country code)""
                required
                disabled={isLoading}
                style={{ width: '100%', padding: '8px', marginBottom: '10px', boxSizing: 'border-box' }}
              /&gt;
              <button type=""submit"" disabled={isLoading} style={{ width: '100%'_ padding: '10px' }}&gt;
                {isLoading ? 'Sending...' : 'Send OTP'}
              </button&gt;
            </&gt;
          ) : (
            // Stage 2: Enter OTP
            <>
              <p&gt;Enter the OTP sent to {phoneNumber}.</p&gt;
              <label htmlFor=""otp"" style={{ display: 'block'_ marginBottom: '5px' }}&gt;OTP:</label&gt;
              <input
                type=""text"" // Use ""text"" and pattern/maxLength for better control
                inputMode=""numeric"" // Hint for numeric keyboard on mobile
                id=""otp""
                value={otp}
                onChange={(e) =&gt; setOtp(e.target.value)}
                maxLength={6} // Match your PIN length configured in Infobip
                pattern=""\d*"" // Allow only digits
                required
                disabled={isLoading}
                autoComplete=""one-time-code"" // Helps browsers/password managers autofill OTP
                style={{ width: '100%', padding: '8px', marginBottom: '10px', boxSizing: 'border-box' }}
              /&gt;
               <button type=""submit"" disabled={isLoading} style={{ width: '100%'_ padding: '10px'_ marginBottom: '10px' }}&gt;
                {isLoading ? 'Verifying...' : 'Verify OTP'}
              </button&gt;
              {/* Button to go back to phone input / allow resend */}
              <button
                type=""button""
                onClick={handleResetFlow}
                disabled={isLoading}
                style={{ width: '100%'_ padding: '10px'_ background: '#eee'_ border: '1px solid #ccc'_ cursor: 'pointer' }}
                &gt;
                 Change Phone Number / Resend OTP
              </button&gt;
            </&gt;
          )}
        </form&gt;
      )}

      {/* Display messages (errors or success) */}
      {message && (
        <p style={{ marginTop: '15px'_ color: isVerified ? 'green' : (message.startsWith('Error:') ? 'red' : 'black') }}&gt;
          {message}
        </p&gt;
      )}
    </div&gt;
  );
}