OTP Verify SMS API

You use the OTP Verify API to send a One Time PIN by SMS in order to prove that a user can be contacted at a specific phone number.
OTP Verifying phone numbers is a mission-critical process you use for:

  • SPAM Protection - prevent spammers from mass-creating messages
  • Hack protection - if you detect suspicious or significant activities, validate that the person using a phone number owns it
  • Reach Users - ensure you have the correct phone number to contact your user when you need to

You can customized the message (which include the PIN) to send to user, so you have freedom to use any language that you like, or add additional promotion and sweeptakes!

There are 2 steps to do an OTP SMS Verification API:

  1. OTP SMS Verification Request API
  2. Verification Check Request API

1. OTP Verify Request SMS API

The following sections describe the request URL to send OTP using AYOSMS! SMS API and all of its associated input parameters and their corresponding values.

Endpoint URL

All the requests to OTP SMS Verification Request API must be submitted to following Endpoint URL:

https://api.ayosms.com/mconnect/gw/verifyrequest.php

Input Parameters

The following table lists each parameter that can be submitted together with the Endpoint URL given above. Note that the first 4 parameters are mandatory while remaining is optional. All parameters are case sensitive.


Parameter Description Example Values
api_key Mandatory AYOSMS! account API Key. 11877c8e0ac231ca93ec2cfcbe1820eb
from Mandatory Sender ID of the message. Up to 11 alphanumeric characters. 7-bit karakter. AYOSMS%21
to Mandatory Destination mobile number in international format (prefixed with country code but without the '+' sign). 62811990000
msg Mandatory Add your "brand" or your "store", OR you can event send customise message from your application. The SMS text to send URL encoded in Unicode UTF-8. Limited to 400 characters. Accept only 7-bit characters.
If there is no "@@PIN@@" in your message, this mean AYOSMS! will send a default OTP message with your "brand".
To send a complete custom message, just put "@@PIN@@" in your message and AYOSMS! will rewrite it with a 6 chars OTP code.

e-storeku
(will be send as "This is PIN for e-storeku: 67GDTJ . This PIN will expired in "5 minutes".)

Your+e-storeku+PIN%3A+%40%40PIN%40%40.+BIGSALE+50%25+OFF%2C+use+this+coupon+%22APRILMOB%22+when+checkout.
(will be send as "Your e-storeku PIN: 67GDTJ . BIGSALE 50% OFF, use this coupon "APRILMOB" when checkout.")
lang Language for "msg" if you use default OTP sentence. Available options are en/id (default id) id
pin_type You can send random number (6 digits) OR random alphanumeric (6 chars) for PIN. Available options are number/alpha (default alpha) number
expired How long (in seconds) the user should be verified. Default value is 300 seconds (5 minutes). Acceptable value is between 60 - 86400.
Any value outside this range will bet set as 300 (5 menit).		 600
delay How long (in seconds) the SMS will be send to user's phone. Default value is null (0 seconds or send immediately). Acceptable value is between 30 - 86400
Any value outside this range will bet set as 0 (immediately).		 60
trx_id Unique internal transaction reference supplied by user to aid with matching delivery receipts. Accept only 7-bit characters. Limited to 36 characters. ae75fa6b-aa5d-4ea9-9ce7-d7db9da760af
dlr To request a deliverey report, you need to set the value to "1". Also, DLR Callback URL should be configured under your Profile setting. 1

Check API Respond

AYOSMS! SMS API returns a response in 2 parts:
  • HTTP Header Status (typically with a HTTP status code 200 OK to indicate successful API call)
  • HTTP Content (In JSON format)

Successful SMS Send Response

A standard successful SMS Send Response shall return status code as '1':
HTTP Header 200 OK
Content 
{
 msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
 trx_id : "123456",
 status : 1,
 secret : "UHYBA3",
 segment : 1,
 expired : 1675318181
}

Error Response: Insufficient Balance

HTTP Header 200 OK
Content 
{
 msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
 trx_id : "123456",
 status : 0,
 secret : "",
 error-text : "ERR002:insufficient balance"
}

Response Attributes

Parameter Description
status Status code. '1' indicates Successful Request, while '0' for Unsuccessful Request (For Error codes, please refer to Error Response Code section below)
msg_id Unique ID to identify a successful SMS send request. Used to trace and match against the ID returned in Delivery Receipt.
trx_id Unique internal transaction reference supplied by user in the API request
secret Secret code which will be use to send a Verification Check API
segment How many SMS segment. AYOSMS! only support GSM 7bit characters. 1-160 characters are counted as 1 SMS segment. More than 160 characters, SMS will be splited into 153 characters per segment. 1 SMS segment cost is equal to 1 SMS request.
error-text Error codes followed by error explanation

Error Response Code

Response Code Description
ERR001 account suspended
ERR002 insufficient balance
ERR005 from error or empty
ERR006 to error or empty
ERR007 msg error, too long or empty
ERR008 api_key not found or sender is disabled or no registered sender
ERR009 sender not registered
ERR012 non GSM 7bit character found
ERR013 more than 400 characters SMS
ERR014 unknown destination number
ERR999 api_key is empty

Example

To send Verification Request API

https://api.ayosms.com/mconnect/gw/verifyrequest.php?api_key=your_unique_api_key&from=AYOSMS%21&to=62811000000&msg=e-storeku&trx_id=mytrxid12345&expired=600&delay=60
Parameter Value in Request Description
api_key your_unique_api_key Your AYOSMS! Account API Key
from AYOSMS%21 (URL encoded for "AYOSMS!") The sender ID (URL encoded)
to 62811000000 The destination mobile number in international format (prefixed with country code but without the '+' sign)
msg e-storeku Your brand. Because there is no @@PIN@@ in the value, message will be send as "This is PIN for e-storeku: 67GDTJ . This PIN will expired in 5 minutes."
trx_id mytrxid12345 Your Transaction ID reference
expired 600 User have 600 seconds (10 minutes) to complete verification process
delay 60 SMS will be send in the next 60 seconds

Delivery Report

A Delivery Receipt (DLR), also known as Delivery Report, is a special type of message which indicates the final state of a SMS.

Requesting A Delivery Report

A Delivery Receipt is not requested by default for every SMS submission. The DLR parameter must set to "1" (dlr=1) in your AYOSMS! SMS API request/

DLR Callback Request

<Your_DLR_Callback_URL>?msg_id=0ca9265c543baf107d3d1feda03aa4d5-1&trx_id=mytrxid12345&from=AYOSMS%21&to=62811000000&delivered=1460019615&status=1&error-text=DELIVERED

Once AYOSMS! receives a delivery receipt, a HTTP DLR callback request will be made to your DLR Callback URL with following parameters described below:

Parameter Description
msg_id Unique ID to match against the ID returned in the SMS API response.
trx_id Unique internal transaction reference supplied by user in the API request.
from Sender ID of the message.
to Destination mobile number in international format (prefixed with country code but without the '+' sign).
delivered Time when AYOSMS! received a Delivery Report from operator (in UNIX Timestamp format, GMT+7).
status Always return '1' for delivered to destination number, and '0' for others (such as permanent failed/pending/buffering etc)
error-text Delivery Receipt error code. (For other DLR error codes, please refer to DLR Error Code section below)
Error-text:
DELIVERED
PENDING
FAILED
EXPIRED
GENERATING MPOSTER URL
NO ROUTE TO DESTINATION NUMBER
SENT NOT DELIVERED

Successful DR Receive Response

Your system HAVE TO respond with plain text "OK". AYOSMS! system will try up to 10 times until we receive an "OK" text from your system.
HTTP Header 200 OK
Content 
OK

2. Verification Check Request API

The following sections describe the request URL to check verification using AYOSMS! SMS API and all of its associated input parameters and their corresponding values.

Endpoint URL

All the requests to OTP SMS Verification Request API must be submitted to following Endpoint URL:
https://api.ayosms.com/mconnect/gw/verifycheck.php

Input Parameters

The following table lists each parameter that can be submitted together with the Endpoint URL given above. Note that the first 4 parameters are mandatory while remaining is optional. All parameters are case sensitive.
Parameter Description Example Values
api_key Mandatory AYOSMS! account API Key. 11877c8e0ac231ca93ec2cfcbe1820eb
pin Mandatory PIN code that has been send to user's phone number. 67GDTJ
secret Mandatory Secret code that has been given when your application call a Verification Request API UHYBA3
msisdncheck If necessary, you could as to verified the phone number as well. Default value is null. Available value is 1. 1
from Become mandatory if you set msisdncheck value to 1. Destination mobile number in international format (prefixed with country code but without the '+' sign). 62811000000

Verification Check Respond

AYOSMS! SMS API returns a response in 2 parts:
  • HTTP Header Status (typically with a HTTP status code 200 OK to indicate successful API call)
  • HTTP Content (In JSON format)

Successful SMS Send Response

A standard successful SMS Send Response shall return status code as '1':
HTTP Header 200 OK
Content 
{
 status : 1,
 error-text : "verified",
 try : 2
}

Balasan Error: PIN Kadaluarsa

HTTP Header 200 OK
Content 
{
 status : 0,
 error-text : "ERR004: pin expired",
 try : 0,
}

Response Attributes

Parameter Description
status Kode status '1' menunjukkan proses verifikasi sukses (kode PIN dan SECRET cocok), sedangkan '0' menunjukkan proses verifikasi gagal (untuk kode Error, silakan lihat penjelasannya dibawah)
error-text Error codes followed by error explanation

Error Response Code

Respond Code Description
ERR001 api_key and secret error, empty or not found
ERR002 check msisdn is not the same with originating msisdn
ERR003 to many retry. maximum verification check is 3 times
ERR004 pin expired
ERR005 check msisdn active but from number not found
ERR006 PIN and secret do not match
ERR007 pin error or empty
ERR999 api_key error

Example

Untuk permintaan Pencocokan OTP dari Pengguna

https://api.ayosms.com/mconnect/gw/verifycheck.php?api_key=your_unique_api_key&pin=67GDTJ&from=62811000000&secret=UHYBA3&msisdncheck=1
Parameter Value in Request Description
api_key 11877c8e0ac231ca93ec2cfcbe1820eb AYOSMS! account API Key.
pin 67GDTJ kode OTP yang dimasukkan oleh pengguna untuk verifikasi setelah mendapatkannya dari SMS
secret UHYBA3 kode secret yang didapat dari respond API Permintaan Pengiriman SMS OTP
from 62811000000 Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+').
msisdncheck 1 proses verifikasi membutuhkan kecocokan nomor ponsel pengguna
AYOSMS!
PT. Ayomobile Media International
Gedung Graha Kencana, Lt.10/G,
Jl. Raya Pejuangan No. 88
Jakarta, 11530
Indonesia
+62.21.53668160
info@ayosms.com


Copyright © 2003-2024
Made in Jakarta, Indonesia
Ohio, US - ENG/ID | 3.15.186.78
FAQ
Register
Payment

Reseller Program
API
Contact
Company Info

FOLLOW US
SMSMOO
AYOMOBILE!