GetOTP Documentation

Multi-Channel OTP

The Multi-Channel OTP allows you to perform multiple OTP via a 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 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 '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/"' \
-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": "3zphnqslxc0n96utnjxz",
  "link": "https://getotp.com/authenticate/3YOikMm9TP/multi/",
  "otp_secret": "etloxfhrg11zkebcpqks"
}

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:"
}

OTP form

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

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

The user needs to complete each OTP form to proceed.

OTP Callback

Every time the user completes the OTP process for a specific channel, a POST request to the callback_url will be made.

For example, if you are using multi-channel email, SMS and voice, 3 callbacks will be made to the callback_url.

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

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