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 ends with a trailing slash:

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

With the following Basic HTTP verification method:

With the following parameters:

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_sms="+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/"' \
-F 'metadata="{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}"' \
-F 'captcha="true"' \
-F 'hide="true"' \
-F 'lang="ja"'

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:

If there is an error with the API call, please refer to this table for details:

{
  "detail": "Verification credentials were not provided."
}

{
  "code": "INV-01",
  "message": "Invalid channel specified"
}

{
  "code": "INV-02",
  "message": "Invalid channel"
}

{
  "code": "INV-03",
  "message": "Email specified but appropriate channel not chosen"
}

{
  "code": "INV-04",
  "message": "Phone number specified but appropriate channel not chosen"
}

{
  "code": "INV-05",
  "message": "Invalid language"
}

{
  "code": "INV-06",
  "message": "Invalid embed mode"
}

{
  "code": "INV-07",
  "message": "Callback URL doesn't match API user domain"
}

{ 
  "code": "INV-08",
  "message": "Success URL doesn't match API user domain"
}

{
  "code": "INV-09",
  "message": "Fail URL doesn't match API user domain"
}

{
  "code": "SUB-01",
  "message": "Request quota exhausted for current plan"
}

{
  "code": "SUB-02",
  "message": "Channel quota exceeded for current plan"
}

{
  "code": "SUB-03",
  "message": "Validity of subscription expired"
}

{
  "code": "SUB-04",
  "message": "Invalid channel requested for current plan"
}

{
  "code": "SUB-05",
  "message": "Invalid lang for plan subscribed. Allowed lang:"
}

Displaying SMS OTP

You needs to redirect a user to the link included in the response.

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

The user will receive an OTP code via SMS and need to fill in their OTP code via the provided form.

OTP Callback

Once the user fills in the OTP form and submits it, a POST request to the callback_url will be made.

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

Your callback_url will receive a POST request with the following payload in a JSON structure:

{
    "otp_id": "8zphnqslxc0n96utnjau",
    "auth_status": "verified",
    "channel": "sms",
    "otp_secret": "otloxfhrg55zkebcpqks",
    "phone_sms": "+60123456789",  
    "ip_address": "10.9.8.7",
    "metadata": "{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}",
    "risk_score": 0.0023
}

Success Redirect

Upon successful OTP, our server will redirect your user to the URL that was defined 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 your convenience. You can use the value to update your application data, but we suggest performing it during the OTP callback.

Failed Redirect

Upon failed OTP, our server will redirect your user to the URL that was defined 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 your convenience. You can use the value to update your application data, but we suggest performing it during the OTP callback.

OTP Flow Summary

To summarize the explanation above here is the OTP flow diagram