Version 2.5C

Introduction

With MobiWeb Asynchronous OTP API you can provide additional security to simple username and password authentication, authenticated transactions, accurately verify users, reduce fraud and reduce two-factor authentication cost (no hardware tokens required).

The Asynchronous OTP API is based on REST. It uses built-in HTTP authentication and HTTP status codes. All data exchange is done in JSON format.

To test the Asynchronous OTP API, you will need a valid API account. If you don't have one yet, please contact us here to register for a FREE test account.

Authentication

https://[HOST]/apis/auth

Asynchronous OTP

https://[HOST]/apis/otp/v3/

Pricing and Balance

https://[HOST]/apis/sms/mt/v2/

[HOST]

Replace [HOST] with your API account domain name or IP.

Authentication

Each request must be accompanied by a valid access_token. access_token are generated upon successful authentication. To authenticate you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value access_token , username and password.

access_token

If the request succeeded, an authentication object is returned, which includes an access_token and a refresh_token. Otherwise, an array of errors is returned. access_token grants you access to make requests.

Setup the Authorization HTTP header with your access_token. Authorization: Bearer dcec4eb6-035c-41a4-9871-82c5bd3ef379

access_token is valid for 30 minutes or for as long it is set through parameter validity, after which it expires. To preserve connection you must refresh with refresh_token. To reset connection please request a new access_token.

refresh_token

To refresh connection you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value "refresh_token" , refresh_token with value the refresh token, provided by a previously successful auth request.

Access from multiple nodes

When using multiple nodes to access API through the same account, please use parameter preserve to avoid each node resetting access_token, effectively blocking all other nodes from accessing the API.

Authentication

POST https://[HOST]/apis/auth
 
POST https://[HOST]/apis/auth
Content-Type : application/json

{
 "type" : "access_token",
 "username" : "myusername",
 "password" : "mypassword"
}
					
{
 "status_code" : 200,
 "status_message" : "OK",
 "payload" : {
	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 "validity_period" : 1800,
	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);

Refresh Connection

POST https://[HOST]/apis/auth
Content-Type : application/json

{
	 "type" : "refresh_token",
	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "0e3f6ecb-7a7e-4d03-a004-d710db8978ab",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "ecbb4d30-6da2-4b78-998e-d01025c648f2"
	 }
}

Send OTP

To send an OTP you must send a generate POST request.

https://[host]/apis/otp/v3/generate

Set parameter mobile with the recipient phone number of the OTP in E.164 format.

If the request succeeded, a response object is returned, which includes the OTP id, the recipient's mobile number, the SMS sender and message and the validity period of the OTP. Otherwise, an error is returned.

Send OTP

POST https://[host]/apis/otp/v3/generate
 
POST https://[HOST]/apis/otp/v3/generate
Content-Type : application/json

{
	 "mobile" : "447546756743"
}

{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : "c6069237320544d7914607c78d79c632",
	 	 "mobile" : "447546756743",
	 	 "sender" : "SECUREPIN",
	 	 "validity" : 600,
     "message" : "Please do not share your password pin. Your password pin is: [PIN]"
	 }
}

Validate OTP

To validate an OTP you must send a validate POST request.

https://[host]/apis/otp/v3/validate/{id}

Replace {id} with the id of the otp.

Set parameter pin with the otp pin and mobile with the recipient's mobile number that received the otp in E.164 format.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Validate OTP

POST https://[host]/apis/otp/v3/validate/{id}
 
POST https://[HOST]/apis/otp/v3/validate/c6069237320544d7914607c78d79c632
Content-Type : application/json

{
	 "pin" : 059647,
	 "mobile" : "447546756743"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Get Balance

To get your account's balance you must send a balance GET request.

https://[host]/apis/sms/mt/v2/balance

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account balance. Otherwise, an error is returned.

Get Balance

GET https://[host]/apis/sms/mt/v2/balance
 
GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);

//Get account balance and print it
echo $client->getBalance();

Get Pricing

To get your account’s pricing details and covered networks, you must make a pricing GET request.

https://[host]/apis/sms/mt/v2/pricing

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. Network objects have attributes operator id, operator countryname, operatorname, operator mobile country code mcc, operator mobile network code mnc and your acount price per SMS sent to this network. Otherwise, an error is returned.

Get Pricing

GET https://[host]/apis/sms/mt/v2/pricing
 
GET https://[host]/apis/sms/mt/v2/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
		 {
			  "id" : 473,
			  "countryname" : "Afghanistan",
			  "operatorname" : "Roshan",
			  "mcc" : "412",
			  "mnc" : "020",
			  "price" : "0.0190"
		 },
		 ..............
		 ]
	 }
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);

//Get account pricing and print it
print_r($client->getPricing(MobiWeb\Rest\Client::SMS));

Errors

OTP API uses 2 levels of errors. Conventional HTTP status codes and application error codes.

OTP API raises errors for many reasons (authentication, invalid parameters, network / server errors etc.). Consult the detailed HTTP status codes and application error codes tables for detailed explanation of response codes.

Please notice that HTTP status code 200 OK does not always result to a successful request. Always consult payload or errors objects to ensure that you interpret result correctly.

Application Errors

OTP API returns errors in an array of objects.

Object Attributes

  • code numeric

    Application error code identifying error.

  • message string

    A human-readable message providing more details about the error.

Errors

{
	 "status_code" : 401,
	 "status_message" : "Unauthorized",
	 "errors" : [
		{
			 "code" : 1005,
			 "message" : "Invalid refresh token"
		}
	 ]
}

HTTP Status Codes

200 OK Everything worked as expected.
201 Created Everything worked as expected.
400 Bad Request The request was unacceptable, often due to invalid JSON format.
401 Unauthorized No valid API key provided.
403 Forbidden The request was rejected.
404 Not Found The requested resource doesn't exist.
422 Unprocessable Request The request unprocessable, often due to invalid parameters.
500 Internal Server Error The service is temporarily unavailable.

Application Error Codes

1001 Invalid token type Invalid parameter.
1004 Invalid authentication credentials Credentials provided is not correct.
1005 Invalid refresh token Invalid parameter.
1009 Invalid access token Access token is invalid.
2103 Invalid parameter (mobile) Invalid parameter.
2104 Invalid parameter (sender) Invalid parameter. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-) or 14 numeric characters (0-9). Special characters are not allowed.
2105 Invalid message Invalid parameter.
2107 Invalid pin Wrong combination of id, pin and mobile or pin expired/already consumed.
2110 Invalid parameter (validity) - (120 - 1800) Invalid parameter.
2121 Service is temporarily unavailable Service is temporarily unavailable.

The AUTH Request

POST

The auth request is used to authenticate and gain access to the SMS API requests.

Parameters

  • type required predefined string "access_token" , "refresh_token"

    The type of the auth request. Can be "access_token" to reset connection or "refresh_token" to refresh connection.

  • validity optional (Default 1800) numeric

    The number of seconds that the access_token will be valid.

  • preserve optional (Default false) boolean true , false

    Preserve an access_token if it already exists and it is not expired. Used when multiple nodes use the same account to access the API.

  • username required for type "access_token" string

    The username of your SMS API account.

  • password required for type "access_token" string

    The password of your SMS API account.

  • refresh_token required for type "refresh_token" string

    The refresh_token. Used when refreshing the connection.

Response

If the request succeeds, an authentication object is returned. An access_token for SMS API requests and a refresh_token to refresh the connection are provided. Returns an array of errors on failure.

Object Attributes

  • access_token string

    The access_token to use with the SMS API requests.

  • validity_period numeric

    The validity period of access_token and refresh_token.

  • refresh_token string

    The refresh_token to use when refreshing the connection.

/auth

POST https://[HOST]/apis/auth
 
POST https://[HOST]/apis/auth
Content-Type : application/json

{
	 "type" : "access_token",
	 "username" : "myusername",
	 "password" : "mypassword"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
	 }
}

The GENERATE Request

POST

The generate POST request is used to generate otp pins and send them via SMS.

Body Parameters

  • mobile required numeric

    The mobile number of the pin recipient in E.164 format.

  • sender optional ( Default "SECUREPIN" ) string

    The sender that will be displayed in the OTP SMS.

  • validity optional ( Default 600 ) numeric

    The validity period of the pin in seconds.

  • message optional ( Default "Please do not share your password pin. Your password pin is: [PIN]" ) string

    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.

  • reference_code optional string

    Set this parameter to your preferred reference code / custom data for this submission.

Response

If the request succeeds, an otp object is returned. Returns an error on failure.

Object Attributes

  • sender string

    The sender of the OTP SMS.

  • mobile string

    The otp pin recipient's mobile number in E.164 format.

  • id string

    The id of created otp pin.

  • validity numeric

    The validity period of created otp pin.

  • imessaged string

    The message of OTP SMS. PIN is masked for security reasons.

  • reference_code string

    The reference code / custom data for this submission.

/generate

POST https://[HOST]/apis/otp/v3/generate
 
POST https://[HOST]/apis/otp/v3/generate
Content-Type : application/json

{
	 "mobile" : "447546756743",
   "sender" : "SecurePIN",
   "validity" : 600,
	 "message" : "Your secure pin is [PIN]",
	 "reference_code" : "899DFF9-9890OPUY"
}

{
   "status_code" : 201,
   "status_message" : "Created",
   "payload" : {
     "sender" : "SecurePIN",
     "mobile" : "447546756743",
     "id" : "c6069237320544d7914607c78d79c632",
     "validity" : 600,
     "message" : "Your secure pin is [PIN]",
     "reference_code" : "899DFF9-9890OPUY"
   }
}

The VALIDATE Request

POST

The validate POST request is used to validate otp pins.

URL Parameters

  • id required numeric

    The id of the otp pin, provided by a previously successful generate request.

Body Parameters

  • mobile required numeric

    The recipient's mobile number of the otp pin.

  • pin required string

    The otp pin.

Response

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

/validate

POST https://[HOST]/apis/otp/v3/validate/{id}
 
POST https://[HOST]/apis/otp/v3/validate/c6069237320544d7914607c78d79c632
Content-Type : application/json

{
     "mobile" : "447546756743",
     "pin" : "725964"
}

{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The BALANCE Request

GET

The balance GET request is used to get an account's balance.

Response

If the request succeeds, an object with the current account's balance is returned. Returns an array of errors on failure.

Object Attributes

  • balance string

    The balance of your account.

/balance

GET https://[host]/apis/sms/mt/v2/balance
 
GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}

The PRICING Request

GET

The pricing GET request is used to get your account’s pricing details and covered networks.

Response

If the request succeeds, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. For an operator with multiple MNCs, a separate record will be displayed for each one. Returns an array of errors on failure.

Object Attributes

  • currency object

    currency object.

    • name string

      The name of your account's currency.

    • symbol string

      The symbol of your account's currency.

  • pricing array

    Array of pricing objects.

    • id numeric

      Mobile network operator id.

    • countryname string

      Mobile network operator country.

    • operatorname string

      Mobile network operator name.

    • mcc string

      Mobile country code of mobile operator.

    • mnc string

      Mobile network code of mobile operator.

    • price string

      Price per SMS for this mobile operator.

/pricing

GET https://[HOST]/apis/sms/mt/v2/pricing
 
GET https://[host]/apis/sms/mt/v2/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
         {
            "id" : 473,
            "countryname" : "Afghanistan",
            "operatorname" : "Roshan",
            "mcc" : "412",
            "mnc" : "020",
            "price" : "0.0190"
         },
         ..............
		 ]
	 }
}