GetOTP Documentation

Multi Channel OTP

The Multi Channel OTP allows you to perform mulitple OTP via combination of Email OTP, SMS OTP or Voice OTP.

Request for Multi Channel OTP API

To request for Multi Channel 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. Can be multiple, seperated by comma Yes String email,sms,voice
email The user email address Yes Optional ali@getotp.test
phone_sms The user mobile phone number (with country code) Yes Optional +60123456789
phone_voice The user mobile phone number (with country code) Yes Optional +60123456789
callback_url Your site callback url when OTP success Yes URL https://mysite.com/payments/otp-callback/
success_redirect_url Where to redirect user after OTP success Yes URL https://mysite.com/payments/qHgZiJQ8YF/otp-complete/
fail_redirect_url Where to redirect user after OTP failed Yes URL https://mysite.com/payments/qHgZiJQ8YF/otp-fail/

Note

Notes on the channel parameter:

  • You can mix and match between available channels. For example Multi OTP with email and voice channel email,voice

Notes on the email, phone_sms and phone_voice parameter:

  • Since the parameter is optional, if omitted the OTP form will have blank field by default
  • If the parameter is present, the OTP form will automatically prefill the field with the provided value
  • For phone_sms and phone_voice, 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 'http://localhost:8090/api/' \
-u 'mTbI2W4hleNdFPxA1iGtHcu5p6MZXf7K:mpktanoshzf4c81e3bydjl76ixr9wugv' \
-F 'channel="email,sms,voice"' \
-F 'email="ali@getotp.test"' \
-F 'phone_sms="+60123456789"' \
-F 'phone_voice="+60123456789"' \
-F 'callback_url="https://mysite.com/payments/otp-callback/"' \
-F 'success_redirect_url="https://mysite.com/payments/qHgZiJQ8YF/otp-complete/"' \
-F 'fail_redirect_url="https://mysite.com/payments/qHgZiJQ8YF/otp-fail/"'

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

{
  "link": "https://getotp.com/authenticate/3YOikMm9TP/multi/",
  "otpid": "3YOikMm9TP"
}

Response data details:

Name Description Data Type Example
link URL to redirect your user to fill OTP code URL https://getotp.com/authenticate/3YOikMm9TP/multi/
otpid The unique OTP ID for this request String 3YOikMm9TP

OTP form

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

https://getotp.com/authenticate/3YOikMm9TP/multi/

User need to complete each OTP form to proceed.

Multi channels 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": "",
    "otp_secret": "otloxfhrg55zkebcpqks",
    "": "",
    "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
otp_secret The unique OTP secret from initial OTP request String cu3089cibcvhfu851428
The value from initial OTP request String
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