API Verifikasi OTP SMS

Anda dapat menggunakan API Verifikasi OTP untuk mengirimkan One Time PIN (OTP) melalui SMS untuk memastikan bahwa pelanggan Anda adalah orang yang seharusnya.
Verifikasi OTP melalui ponsel sangatlah penting untuk proses-proses seperti:

  • Menghindari SPAM - untuk melindungi proses pendaftaran akun atau registrasi
  • Menghindari Hack - Anda dapat membuat aplikasi Anda untuk melakukan verifikasi pengguna untuk proses-proses yang sangat penting, seperti transaksi online
  • Memastikan Data Pelanggan - untuk membuat database nomor ponsel pelanggan Anda yang akurat

Anda dapat membuat pesan SMS sendiri (yang berisi kode One Time PIN) yang nantinya akan dikirimkan oleh AYOSMS!, sehingga Anda dapat menggunakan bahasa asing misalnya, atau menambahkan promosi/diskon layanan Anda!

Secara garis besar, ada 2 API utama untuk melakukan verifikasi ini, yaitu:

  1. API Permintaan Pengiriman SMS OTP
  2. API Pencocokan OTP dari Pengguna

1. API Permintaan Pengiriman SMS OTP

Pada bagian ini akan dijelaskan mengenai penggunaan API Permintaan Pengiriman SMS OTP.

Endpoint URL

Seluruh permintaan untuk API Permintaan Pengiriman SMS OTP harus ditujukan ke alamat URL sebagai berikut:
https://api.ayosms.com/mconnect/gw/verifyrequest.php

Input Parameters

Tabel berikut ini adalah daftar parameter bisa dikirimkan ke alamat URL diatas. Perhatikan bahwa 4 parameter pertama adalah WAJIB dikirimkan sedangkan lainnya adalah optional. Semua parameter bersifat case sensitive.
Parameter Deskripsi Contoh Nilai
api_key Wajib API Key di akun AYOSMS!. 11877c8e0ac231ca93ec2cfcbe1820eb
from Wajib Pengirim pesan SMS. Maksimum 11 karakter. 7-bit karakter. AYOSMS%21
to Wajib Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+'). 62811990000
msg Wajib Berisi "merek" atau "nama layanan Anda", ATAU dapat juga berisi pesan apapun dari aplikasi Anda. Isian ini harus di URL encode dalam karakter Unicode UTF-8. Terbatas 400 karakter (sudah termasuk 6 karakter kode OTP). Hanya menerima 7-bit karakter.
Isian pesan ini akan diperiksa apakah mengandung kata "@@PIN@@" atau tidak.
Jika ada kata "@@PIN@@" maka akan otomatis diubah menjadi 6 karakter kode OTP. Jika tidak ada kata "@@PIN@@" maka akan dikirimkan pesan OTP default dengan mencantumkan "merek" atau "nama layanan Anda".

e-storeku
(akan terkirim "Ini adalah kode PIN untuk e-storeku: 67GDTJ. PIN ini akan kadaluarsa dalam 5 menit")

Kode+e-storeku%3A+%40%40PIN%40%40.+Diskon+50%25+untuk+pembelian+pertama+bulan+April.
(akan terkirim "Kode e-storeku: 67GDTJ. Diskon 50% untuk pembelian pertama bulan April.")
lang Bahasa untuk pesan default pada isian parameter "msg". Opsi tersedia en/id (default id) id
pin_type PIN yang dikirimkan apakah dalam bentuk ANGKA ACAK (6 digit) atau KOMBINASI HURUF & ANGKA ACAK (6 karakter). Opsi tersedia number/alpha (default alpha) number
expired Lama kadaluarsa kode OTP ini dalam satuan detik. Default adalah selama 300 detik (5 menit). Nilai yang dapat diberikan adalah antara 60 - 86400.
Jika nilai yang diisi tidak dalam rentang tersebut maka otomatis akan dianggap menjadi 300 (5 menit).		 600
delay Waktu tunda dalam detik yang dibutuhkan untuk pengiriman SMS OTP ke nomor tujuan. Default adalah segera (0 detik). Nilai yang dapat diberikan adalah antara 30 - 86400
Jika nilai yang diisi tidak dalam rentang tersebut maka otomatis akan dianggap menjadi 0 (0 detik).		 60
trx_id Kode Unik yang dikirim dari pengguna AYOSMS! untuk membantu referensi pada pelaporan SMS. Terbatas 36 karakter. Hanya menerima 7-bit karakter. ae75fa6b-aa5d-4ea9-9ce7-d7db9da760af
dlr Jika Anda ingin menerima status laporan pengiriman SMS "Delivery Report" dari operator maka isi parameter ini dengan '1'. Status laporan ini belum tentu tersedia di semua operator. Alamat URL "delivery report" dapat diisi di halaman pengaturan akun setelah login ke AYOSMS! Webtool. 1

Balasan Permintaan API

SMS API AYOSMS! akan memberikan balasan dalam 2 bentuk:
  • HTTP Header Status (biasanya dalam bentuk kode 200 OK yang menunjukkan bahwa permintaan API sudah sukses diterima)
  • HTTP Content (dalam format JSON)

Balasan SMS Sukses

Standar balasan API SMS adalah kode status=1:
HTTP Header 200 OK
Content 
{
 msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
 trx_id : "123456",
 status : 1,
 secret : "UHYBA3",
 segment : 1,
 expired : 1675318181
}

Balasan Error: 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 Deskripsi
status Kode status '1' menunjukkan permintaan sukses diterima, sedangkan '0' menunjukkan permintaan gagal diterima (untuk kode Error, silakan lihat penjelasannya dibawah)
msg_id ID unik untuk identifikasi setiap permintaan pengiriman SMS. Digunakan juga untuk mencocokkan setiap laporan pengiriman (Delivery Report).
trx_id Kode unik referensi yang diisi oleh user saat melakukan permintaan pengiriman SMS melalui API
secret Kode unik yang akan digunakan untuk proses pencocokan verifikasi selanjutnya saat pengguna memasukkan kode OTP dari SMS yang diterima
segment Jumlah SMS segmen yang dikirimkan. AYOSMS! hanya mendukung GSM 7bit karakter. 1-160 karakter akan dihitung sebagai 1 segmen SMS. Lebih dari 160 karakter maka SMS akan dihitung per 153 karakter sebagai 1 segment. 1 segment SMS dihitung seharga 1 SMS.
error-text Kode error diikuti dengan penjelasannya

Balasan Kode Error

Kode Balasan Deskripsi
ERR001 akun user dibatalkan
ERR002 pulsa tidak mencukupi
ERR005 parameter "from" salah atau kosong
ERR006 parameter "to" salah atau kosong
ERR007 parameter "msg" salah atau kosong
ERR008 parameter "api_key" tidak ditemukan
ERR009 pengirim/masking tidak terdaftar
ERR012 ditemukan karakter non GSM 7bit (saat ini AYOSMS! hanya mendukung karakter GSM 7bit)
ERR013 lebih dari 400 karakter
ERR014 tujuan nomor tidak diketahui
ERR999 parameter "api_key" kosong

Contoh

Untuk permintaan pengiriman SMS OTP

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 API Key di akun AYOSMS!.
from AYOSMS%21 (URL encoded dari "AYOSMS!") Pengirim pesan SMS. Maksimum 11 karakter. 7-bit karakter.
to 62811000000 Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+').
msg e-storeku Berisi merek "e-storeku". Karena tidak ada kata "@@PIN@@" maka akan dikirimkan pesan OTP default, yaitu: "Ini adalah kode PIN untuk e-storeku: 67GDTJ. PIN ini akan kadaluarsa dalam 5 menit"
trx_id mytrxid12345 Kode Unik yang dikirim dari pengguna AYOSMS! untuk membantu referensi pada pelaporan SMS. Terbatas 36 karakter. Hanya menerima 7-bit karakter.
expired 600 Kode OTP akan kadaluarsa dalam 600 detik (10 menit)
delay 60 Kode OTP akan dikirimkan dalam waktu 60 detik kedepan

Laporan Pengiriman

Laporan Pengiriman (Delivery Receipt (DLR)), adalah pesan yang dikirimkan operator untuk menunjukkan posisi terakhir dari pesan SMS kita.

Meminta Laporan Pengiriman

Jika pada saat permintaan pengiriman mengisi parameter "dlr=1" maka sistem akan memberikan umpan balik sesaat setelah sistem AYOSMS! menerima unpan balik permintaan pengiriman SMS dari operator.

Permintaan Umpan Balik DLR

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

Sesaat setelah AYOSMS! menerima laporan pengiriman dari operator (DLR), pengiriman umpan balik HTTP DLR akan dikirimkan ke URL Umpan Balik DLR Anda dengan parameter-parameter sebagai berikut:

Parameter Deskripsi
msg_id ID unik untuk identifikasi setiap permintaan pengiriman SMS. Digunakan juga untuk mencocokkan setiap laporan pengiriman (Delivery Report).
trx_id Kode unik referensi yang diisi oleh user saat melakukan permintaan pengiriman SMS melalui API
from Pengirim pesan SMS.
to Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+').
delivered Waktu saat AYOSMS! menerima status DR dari operator (dalam format UNIX TIMESTAMP, GMT+7).
status Selalu berisi '1' jika SMS terkirim sampai ke nomor tujuan, dan '0' untuk gagal (seperti SMS kadaluarsa/nomor tujuan tidak aktif/handset error dll)
error-text Berisi keterangan lebih detail mengenai kegagalan. (Lihat keterangan error-text dibawah)
Error-text:
DELIVERED
PENDING
FAILED
EXPIRED
GENERATING MPOSTER URL
NO ROUTE TO DESTINATION NUMBER
SENT NOT DELIVERED

Balasan dari Sistem Anda

Sistem Anda HARUS membalas dengan text "OK" saat sistem AYOSMS! mengirimkan DR. Sistem AYOSMS! akan mencoba sampai 10x jika sistem Anda tidak memunculkan text "OK".
HTTP Header 200 OK
Content 
OK

2. API Pencocokan OTP dari Pengguna

Pada bagian ini akan dijelaskan mengenai penggunaan API Pencocokan OTP dari Pengguna.

Endpoint URL

Seluruh permintaan untuk API Pencocokan OTP dari Pengguna harus ditujukan ke alamat URL sebagai berikut:
https://api.ayosms.com/mconnect/gw/verifycheck.php

Input Parameters

Tabel berikut ini adalah daftar parameter bisa dikirimkan ke alamat URL diatas. Perhatikan bahwa 4 parameter pertama adalah WAJIB dikirimkan sedangkan lainnya adalah optional. Semua parameter bersifat case sensitive.
Parameter Deskripsi Contoh Nilai
api_key Wajib API Key di akun AYOSMS!. 11877c8e0ac231ca93ec2cfcbe1820eb
pin Wajib Kode OTP yang diinput oleh pengguna yang didapat dari hasil pengiriman SMS OTP. 67GDTJ
secret Wajib Berisi kode rahasia yang didapat dari respond panggilan API Permintaan Pengiriman SMS OTP UHYBA3
msisdncheck Untuk mekanisme OTP dimana pengguna harus mengiriman kode OTP menggunakan ponsel mereka ke nomor tujuan tertentu (contoh: nomor pendek/premium), maka proses verifikasi dapat diperintahkan juga untuk mencocokkan nomor ponsel pengguna (saat dikirimi SMS OTP dengan saat pengguna mengirim balik kode OTP ke nomor tujuan tertentu). Nilai yang mungkin adalah null atau 1, (default null) 1
from Hanya berguna jika opsi msisdncheck=1. Nomor ponsel pengguna yang dikirimi SMS OTP. Menggunakan format internasional (prefix dengan kode negara tanpa tanda '+'). 62811000000

Balasan Pencocokan

SMS API AYOSMS! akan memberikan balasan dalam 2 bentuk:
  • HTTP Header Status (biasanya dalam bentuk kode 200 OK yang menunjukkan bahwa permintaan API sudah sukses diterima)
  • HTTP Content (dalam format JSON)

Balasan SMS Sukses

Standar balasan API SMS adalah kode status=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 Deskripsi
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 Kode error diikuti dengan penjelasannya

Balasan Kode Error

Kode Balasan Deskripsi
ERR001 parameter "api_key" dan kode secret salah, tidak ditemukan atau kosong
ERR002 nomor ponsel tidak cocok dengan nomor ponsel asal yang dikirimi SMS OTP
ERR003 terlalu banyak kegagalan proses pencocokan. maksimum aktifitas pencocokan adalah 3x
ERR004 PIN kadaluarsa
ERR005 msisdncheck ada namun nomor ponsel tidak ditermukan
ERR006 PIN dan secret tidak cocok
ERR007 PIN salah atau kosong
ERR999 parameter "api_key" kosong

Contoh

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 API Key di akun AYOSMS!.
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-2025
Made in Jakarta, Indonesia
Ohio, US - IND/EN | 216.73.216.40
Tanya Jawab
Daftar
Pembayaran

Program Reseller
API
Kontak
Info Perusahaan

IKUTI KAMI
SMSMOO
AYOMOBILE!