GetOTP Documentation

SMS OTP

The SMS OTP allows you to perform OTP via SMS.

Request for SMS OTP API

To request for SMS OTP, make a POST request to our OTP endpoint. Take note that our OTP endpoint ending with trailing slash:

https://otp.dev/api/verify/

With the following Basic HTTP authentication method:

Description Required Data Type Example
Your API Key Yes String mtbi2w4hlendfpxa1igthcu5p6mzxf7k
Your API Token Yes String mpktanoshzf4c81e3bydjl76ixr9wugv

Note

  • Grab your API key and API token from this page
  • You can create maximum 3 count of API keys
  • Your API call counts will be limit depending on your active subscription

With the following parameters:

Name Description Required Data Type Example
channel Channel for delivering OTP Yes String sms
phone_sms The user mobile phone number (with country code) No String +60123456789
callback_url Your site callback url when OTP success No URL https://mysite.test/payments/otp-callback/
success_redirect_url Where to redirect user after OTP success Yes URL https://mysite.test/payments/qHgZiJQ8YF/otp-complete/
fail_redirect_url Where to redirect user after OTP failed Yes URL https://mysite.test/payments/qHgZiJQ8YF/otp-fail/

Note

Notes on the phone_sms parameter:

  • Since the parameter is optional, if omitted the OTP form will have blank phone field by default
  • If the parameter is present, the OTP form will automatically prefill the phone field with the provided value
  • Developer must provide phone number with country code, and start with plus (+) symbol as per example

Examples

Below is an example request using cURL:

curl -L -X POST 'https://otp.dev/api/verify/' \
-u 'mtbi2w4hlendfpxa1igthcu5p6mzxf7k:mpktanoshzf4c81e3bydjl76ixr9wugv' \
-F 'channel="sms"' \
-F 'phone_number="+60123456789"' \
-F 'callback_url="https://mysite.test/payments/otp-callback/"' \
-F 'success_redirect_url="https://mysite.test/payments/qHgZiJQ8YF/otp-complete/"' \
-F 'fail_redirect_url="https://mysite.test/payments/qHgZiJQ8YF/otp-fail/"'

The response would be a JSON structure, returned with HTTP 200 Code status code:

{
  "otp_id": "vbiwkf149jixuzhao85z",
  "link": "https://otp.dev/api/ui/verify/vbiwkf149jixuzhao85z/sms/",
  "otp_secret": "230q4j20kk9rw5b1zrh4"
}

Response data details:

Name Description Data Type Example
otp_id The unique OTP ID for this request String l4lckl9qkx2h54k58hnj
link URL to redirect your user to fill OTP code URL https://otp.dev/api/ui/verify/vbiwkf149jixuzhao85z/sms/
otp_secret The unique OTP secret for this request String 4gdpu9li6i9654dk6mui

Displaying SMS OTP

Developer need to redirect the user to included link in the response.

https://otp.dev/api/ui/verify/vbiwkf149jixuzhao85z/sms/

User will received OTP code via SMS, and need to fill their OTP code via provided form.

SMS OTP form

OTP Callback

Once user fill in the OTP form and submit, a POST request to the callback_url will be made.

https://mysite.test/payments/otp-callback/

Your callback_url will received POST request with the following payload:

{
    "otp_id": "8zphnqslxc0n96utnjau",
    "auth_status": "verified",
    "channel": "sms",
    "otp_secret": "otloxfhrg55zkebcpqks",
    "phone_sms": "+60123456789",
    "ip_address": "10.9.8.7"
}
Name Description Data Type Example
otp_id The unique OTP ID from initial OTP request String a3rmm7nbe6thgxiaancj
auth_status The OTP status String verified
not_verified
channel The OTP channel String sms
otp_secret The unique OTP secret from initial OTP request String cu3089cibcvhfu851428
phone_sms The value from initial OTP request String +60123456789
ip_address The IP address of the user going through authentication String 10.9.8.7

Note

Notes on the auth_status parameter:

  • The value is depend on the whether user input the correct OTP or not
  • Correct OTP will return verified value
  • Invalid OTP will return not_verified value

Success Redirect

Upon success OTP, our server will redirect your user to url that was define in success_redirect_url. This is useful to show success confirmation to the user.

https://mysite.test/payments/qHgZiJQ8YF/otp-complete/?otp_id=m1zBsh2L0c

Note that we include the otp_id in the redirect URL for developer convenience. You can use the value to update your application data, but we suggested to perform it during OTP callback.

Failed Redirect

Upon failed OTP, our server will redirect your user to url that was define in fail_redirect_url. This is useful to show fail confirmation to the user.

https://mysite.test/payments/qHgZiJQ8YF/otp-fail/?otp_id=m1zBsh2L0c

Note that we include the otp_id in the redirect URL for developer convenience. You can use the value to update your application data, but we suggested to perform it during OTP callback.

OTP Flow Summary

To summarize the explanation above, here is the OTP flow diagram

GetOTP OTP flow

OTP Demo

Checkout live demo here

GetOTP Live Demo