GetOTP Documentation

Email OTP

The Email OTP allows you to perform OTP via email.

Request for Email OTP API

To request for Email 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 email
email The user email address No String ali@getotp.test
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 email parameter:

  • Since the parameter is optional, if omitted the OTP form will have blank email field by default
  • If the parameter is present, the OTP form will automatically prefill the email field with the provided value

Examples

Below is an example request using cURL:

curl -L -X POST 'https://otp.dev/api/verify/' \
-u 'mtbi2w4hlendfpxa1igthcu5p6mzxf7k:mpktanoshzf4c81e3bydjl76ixr9wugv' \
-F 'channel="email"' \
-F 'email="ali@getotp.test"' \
-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": "kpb9c0a357pdf4jaz05c",
  "link": "https://otp.dev/api/ui/verify/kpb9c0a357pdf4jaz05c/email/",
  "otp_secret": "dxn07vdzqy7wfblk89r9"
}

Response data details:

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

Displaying Email OTP

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

https://otp.dev/api/ui/verify/kpb9c0a357pdf4jaz05c/email/

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

Email 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": "email",
    "otp_secret": "otloxfhrg55zkebcpqks",
    "email": "ali@getotp.test",
    "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 email
otp_secret The unique OTP secret from initial OTP request String cu3089cibcvhfu851428
email The value from initial OTP request String ali@getotp.test
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