One Time Password Service

The One Time Password service provides endpoints which allows the generation and sending of One-Time Passwords (OTPs) which can be used as an alternative to username and password authentication.

Endpoints

Is OTP Enabled

GET onetimepassword/isOTPEnabled.json

Determine whether or not OTP login is enabled for the given merchant. Can be used to conditionally render an OTP-based login screen.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • enabled (Boolean) – (required)
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Generate and Send SMS OTP Code

POST onetimepassword/generateAndSendSMSOTP.json

If configured for the program, generates an OTP code, and, if the provided phone number matches a user in the system, sends the code to the user via SMS. For security, returns a success even if there are no matching users with the phone number.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • mobilePhone (String) – (required) The mobile phone number associated with the user.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Error Codes

The following are the possible codes and messages that can be returned by the One Time Password Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
is_otp_enabled.system_error System error
generate_send_otp.system_error System error
generate_send_otp.feature_disabled SMS OTP feature not enabled for this merchant
generate_send_otp.duplicate_phone_numbers Multiple users were found with this phone number
generate_send_otp.invalid_inputs The provided mobile phone was invalid: <error reason>
generate_send_otp.rate_limited Too many codes have been sent to this number. Please try again later