Version 3.0.1

Implemented OTP SMS API functionality and added examples in the README.md
mobiweb · Apr 21, 2023 · 265c6fd · 265c6fd
1 parent 074cfc5
commit 265c6fd
Show file tree

Hide file tree

Showing 8 changed files with 255 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -367,6 +367,90 @@ print_r($client->getPricing(MobiWeb\Rest\Client::HLR));
 ?>
 ```
 
+### OTP SMS API
+### Generate and send OTP
+
+```php
+<?
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new MobiWeb\Rest\Client($username, $password);
+
+//Generate OTP and send it via SMS to a mobile number
+$otp = $client->generate(
+  "44xxxxxxxxxx", //The mobile number in international E.164 format.
+  "SECUREPIN", //The sender that will be displayed in the OTP SMS. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
+  "Please do not share your password pin. Your password pin is: [PIN]", //The text message of OTP SMS. Remember to put placeholder [PIN] in the message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters. 
+  600, //The validity period of the pin in seconds. The default value is 600 seconds (10 minutes).
+  );
+
+//Print the generate OTP result. Remember to store the mobile number and the OTP id for later use.
+print_r($otp);
+
+?>
+```
+
+### Validate OTP
+
+```php
+<?
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new MobiWeb\Rest\Client($username, $password);
+
+//Validate a previously generated OTP with the OTP ID. OTP is provided by the mobile number subscriber.
+$otp = $client->validate(
+  "564xxx", //The OTP ID returned by the generated OTP.
+  "44xxxxxxxxxx", //The mobile number of the subscriber in international E.164 format.
+  "265xxx", //The OTP provided by the mobile number subscriber. 
+);
+
+//Print the OTP validation attempt result. If result is TRUE, OTP is validated.
+echo $otp;
+
+?>
+```
+
+### Get account balance
+
+```php
+<?php
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new MobiWeb\Rest\Client($username, $password);
+
+//Get account balance and print it
+echo $client->getBalance();
+
+?>
+```
+
+### Get account pricing
+
+```php
+<?php
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new MobiWeb\Rest\Client($username, $password);
+
+//Get account OTP pricing and print it
+print_r($client->getPricing(MobiWeb\Rest\Client::OTP));
+
+?>
+```
+
 ## Getting help
 
 If you need help installing or using the library, please [contact us][MobiWebSupportCenter].

diff --git a/src/MobiWeb/Http/Client.php b/src/MobiWeb/Http/Client.php
@@ -7,6 +7,7 @@ class Client {
     const GET = "GET";
     const POST = "POST";
     const HTTP_OK = "200";
+    const HTTP_CREATED = "201";
     const HTTP_BAD = "400";
     const HTTP_UNAUTH = "401";
     const HTTP_NOTFOUND = "404";

diff --git a/src/MobiWeb/Rest/Client.php b/src/MobiWeb/Rest/Client.php
@@ -4,6 +4,8 @@
 
 use MobiWeb\Rest\Authentication as Auth;
 use MobiWeb\Rest\Message;
+use MobiWeb\Rest\HLR;
+use MobiWeb\Rest\OTP;
 use MobiWeb\Rest\Utility as Util;
 
 class Client {
@@ -12,6 +14,7 @@ class Client {
     const API_ENDPOINT = "https://sms.solutions4mobiles.com/apis"; 
     const HLR = "hlr"; 
     const SMS = "sms";
+    const OTP = "otp";
 
 
     public function __construct(string $username = null, string $password = null){
@@ -37,6 +40,26 @@ public function broadcast(array $args): array{
 
     }
 
+    public function generate(string $mobile, string $sender, string $message, int $validity){
+
+        if (!$mobile) {
+            throw new \Exception("Mobile number is required to generate an OTP");
+        }
+
+        return OTP::generate($this->auth, $mobile, $sender, $message, $validity);
+
+    }
+
+    public function validate(string $id, string $mobile, string $pin): bool{
+
+        if (!$mobile || !$id || !$pin) {
+            throw new \Exception("Mobile number, OTP pin and OTP ID is required to validate an OTP");
+        }
+
+        return OTP::validate($this->auth, $id, $mobile, $pin);
+
+    }
+
     public function lookup(string $mobile): array{
 
         if (!$mobile) {

diff --git a/src/MobiWeb/Rest/OTP.php b/src/MobiWeb/Rest/OTP.php
@@ -0,0 +1,79 @@
+<?php
+
+namespace MobiWeb\Rest;
+
+use MobiWeb\Rest\Authentication as Auth;
+use MobiWeb\Rest\Client as APIClient;
+use MobiWeb\Http\Client as HttpClient;
+use MobiWeb\Rest\Error as APIError;
+
+class OTP {
+
+    const GENERATE_ENDPOINT = "/otp/v3/generate";
+    const VALIDATE_ENDPOINT = "/otp/v3/validate/";
+    const OTP_METHOD = "POST";
+
+    public static function generate(Auth $auth = null, string $mobile, string $sender = "SECUREPIN", string $message = "Please do not share your password pin. Your password pin is: [PIN]", int $validity = 600){
+
+        if (!$auth) {
+            throw new \Exception("Cannot generate OTP without authentication");
+        }
+
+        $access_token = $auth->getAccessToken();
+        if(!$access_token){
+            throw new \Exception("Cannot retrieve Access Token");
+            return false;
+        }
+
+        $http = new HttpClient();
+        $headers = array();
+        $headers["Authorization"] = "Bearer " . $access_token;
+        $body = new \stdClass();
+        $body->mobile = $mobile;
+        $body->sender = $sender;
+        $body->message = $message;
+        $body->validity = $validity;
+
+        $executedRequest=$http->request(APIClient::API_ENDPOINT . OTP::GENERATE_ENDPOINT, OTP::OTP_METHOD, $headers, $body);
+
+        if($executedRequest->response->body->status_code != HttpClient::HTTP_CREATED){
+            $apiError = new APIError($executedRequest->response->body->status_code, $executedRequest->response->body->status_message, $executedRequest->response->body->errors);
+            throw new \Exception($apiError->print());
+            return false;
+        }
+
+        return array($executedRequest->response->body->payload);
+    }
+
+    public static function validate(Auth $auth = null, string $id, string $mobile, string $pin): bool{
+
+        if (!$auth) {
+            throw new \Exception("Cannot validate OTP without authentication");
+        }
+
+        $access_token = $auth->getAccessToken();
+        if(!$access_token){
+            throw new \Exception("Cannot retrieve Access Token");
+            return false;
+        }
+
+        $http = new HttpClient();
+        $headers = array();
+        $headers["Authorization"] = "Bearer " . $access_token;
+        $body = new \stdClass();
+        $body->mobile = $mobile;
+        $body->pin = $pin;
+
+        $executedRequest=$http->request(APIClient::API_ENDPOINT . OTP::VALIDATE_ENDPOINT . $id, OTP::OTP_METHOD, $headers, $body);
+
+        if($executedRequest->response->body->status_code != HttpClient::HTTP_OK){
+            $apiError = new APIError($executedRequest->response->body->status_code, $executedRequest->response->body->status_message, $executedRequest->response->body->errors);
+            throw new \Exception($apiError->print());
+            return false;
+        }
+
+        return true;
+
+    }
+
+}
diff --git a/src/MobiWeb/Rest/Utility.php b/src/MobiWeb/Rest/Utility.php
@@ -13,6 +13,7 @@ class Utility {
     const BALANCE_METHOD = "GET";
     const PRICING_SMS_ENDPOINT = "/sms/mt/v2/pricing";
     const PRICING_HLR_ENDPOINT = "/hlr/v2/pricing";
+    const PRICING_OTP_ENDPOINT = "/otp/v3/pricing";
     const PRICING_METHOD = "GET";
 
 
@@ -66,6 +67,9 @@ public static function getPricing(Auth $auth = null, string $service): array{
             case APIClient::HLR:
                 $pricing_endpoint = Utility::PRICING_HLR_ENDPOINT;
                 break;
+            case APIClient::OTP:
+                $pricing_endpoint = Utility::PRICING_OTP_ENDPOINT;
+                break;
         }
 
         $executedRequest=$http->request(APIClient::API_ENDPOINT . $pricing_endpoint, Utility::PRICING_METHOD, $headers);
@@ -84,6 +88,7 @@ public static function getPricing(Auth $auth = null, string $service): array{
 
         switch($service){
             case APIClient::SMS:
+            case APIClient::OTP:
                 foreach ($pricing as $key => $value)$arr_pricing[$value->id] = array("countryname" => $value->operatorname, "operator" => $value->operatorname, "mcc" => $value->mcc, "mnc" => $value->mnc, "price" => $value->price, "currency" => $currency);
                 break;
             case APIClient::HLR:

diff --git a/tests/generate_otp.php b/tests/generate_otp.php
@@ -0,0 +1,24 @@
+<?php
+
+require __DIR__ . '/../../../autoload.php'; // Loads MobiWeb package
+
+use MobiWeb\Rest\Client as APIClient;
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new APIClient($username, $password);
+
+//Generate OTP and send it via SMS to a mobile number
+$otp = $client->generate(
+  "44xxxxxxxxxx", //The mobile number in international E.164 format.
+  "SECUREPIN", //The sender that will be displayed in the OTP SMS. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
+  "Please do not share your password pin. Your password pin is: [PIN]", //The text message of OTP SMS. Remember to put placeholder [PIN] in the message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters. 
+  600, //The validity period of the pin in seconds. The default value is 600 seconds (10 minutes).
+  );
+
+//Print the generate OTP result. Remember to store the mobile number and the OTP id for later use.
+print_r($otp);
+
+?>
diff --git a/tests/get_otp_pricing.php b/tests/get_otp_pricing.php
@@ -0,0 +1,16 @@
+<?php
+
+require __DIR__ . '/../../../autoload.php'; // Loads MobiWeb package
+
+use MobiWeb\Rest\Client as APIClient;
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new APIClient($username, $password);
+
+//Get account OTP pricing and print it
+print_r($client->getPricing(APIClient::OTP));
+
+?>
diff --git a/tests/validate_otp.php b/tests/validate_otp.php
@@ -0,0 +1,23 @@
+<?php
+
+require __DIR__ . '/../../../autoload.php'; // Loads MobiWeb package
+
+use MobiWeb\Rest\Client as APIClient;
+
+//Your account username and password
+$username = "";
+$password = "";
+
+$client = new APIClient($username, $password);
+
+//Validate a previously generated OTP with the OTP ID. OTP is provided by the mobile number subscriber.
+$otp = $client->validate(
+  "564xxx", //The OTP ID returned by the generated OTP.
+  "44xxxxxxxxxx", //The mobile number of the subscriber in international E.164 format.
+  "265xxx", //The OTP provided by the mobile number subscriber. 
+);
+
+//Print the OTP validation attempt result. If result is TRUE, OTP is validated.
+echo $otp;
+
+?>