Two Factor Authentication

Two Factor Authentication, also known as 2FA, is the dynamic generation of a numeric/alphanumeric/alphabetical
code that authenticates the user for a single transaction or session. The code or one-time password (OTP) can be
sent to the customer via SMS.

Pre-start checklist

  • User name & password. If you don’t have an account, you can create one at Gupshup Enterprise SMS.
  • For 2FA Account configuration please share the details as mentioned in the table with the support team.

Parameters

Description

Enterprise Account ID

Numeric Account Id

OTP Expiry in Seconds

Expiry time of an OTP for an enterprise user

OTP Retry in Seconds

Number of seconds an enterprise user has to wait before the user can resend an OTP

Allowed OTP Verification Attempts

Number of attempts allowed to verify an OTP

Parameters

Parameter

Value

Description

userid

Account number
provided by Enterprise
SMS GupShup

The number must be in pure numeric format with no special characters.

password

UrlEncoded string of
UTF-8 characters

Password provided by Gupshup for authentication of user ID. The
password must be the same as used to log on to the Enterprise SMS
GupShup website.

method

TWO_FACTOR_AUTH

Method for performing a specific action.

v

1.1

The default version is 1.1, unless otherwise specified.

Phone_no

Phone no. of the
receiver

The number must be in pure numeric format with no special characters

msg

UrlEncoded string of
UTF-8 characters

The message that needs to be sent. It can contain alphanumeric & special characters. The message must contain
%code%

msg_type

Text or Unicode_text

Indicates the type of the message to be sent. Default is “text”.

format

TEXT, XML, JSON

Specific format for response message

otpCodeLength

Numeric

This is the length of an OTP. It must be a positive integer less than or
equals to 10.

otpCodeType

NUMERIC,
ALPHABETIC or
ALPHANUMERIC

This parameter specifies the type of an OTP. 3 values are permitted
NUMERIC (only numbers), ALPHABETIC (only alphabets),
ALPHANUMERIC (mix of numbers and alphabets).

otp_code

OTP to be verified

The API verifies OTP if given otherwise sends OTP (This is the only
difference between Send OTP and Verify OTP).

Generate and send OTP

Sample API request

https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=XXXXXXXX&password=XXXXX&method=
TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXXX&msg=
Your%20OTP%20code%20is%20%25code%25&format=text&otpCodeLength=4&otpCodeType=NUMERIC

Response Message

success | 919XXXXXXXXX | 3545912456442574189 | OTP sent

Verify OTP

Sample API request

https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=XXXXXXX&password=XXXXXX&
method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX& otp_code=1564

Response Message

success | 919XXXXXXXXX | 3545913275288024429 | OTP matched

Encrypted payload for Two Factor Authentication API call

Steps for Encryption

  1. Form a querystring using the rest of API parameters and its values.
    Example: password=XXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX&msg=Y
    our%20OTP%20code%20is%20%25code%25&format=text&otpCodeLength=4&otpCodeType=NUMERIC.
  2. Encrypt the querystring using the AES encryption algorithm(256 bit algorithm)
  • Use only GCM mode
  • Length of IV (Initialization Vector) parameter should be 12 bytes. IV value should be unique for every API
    request/call.
  • Length of authentication tag should be 16 bytes
  1. Output of AES Encryption (256 bit) should be encoded using base 64 Urlsafe.
  2. The Base64 encoded encrypted cipher will be passed as a payload in encrdata parameters.
  3. Sample of encrypted payload using above steps:
    VEYcNxNQQcZ0t6VcfxZwzTpeTmBb0UKPYORWA1_VEIaGWrg7zS6aOdUYvmXCpOZbyGs2w9xKA_c43r0OnrL3KHUgUrvIY1_5eOm8y5zoWyCaWbV2OKFpa5yZQe0GQrm8PZyBJYIDgE7qswrrPj005nZZyFiCtDP50UDnaeg6RTVKV748lkURa1RDcs3lMkh3n5UsaNM5TU_lhkC0yreyuuNu8mlRQmNFDMUMWOfvNvhLL_H4

The following are the required parameters

Parameter

Description

userid

Specify the user id provided by Gupshup. This must be sent in plaintext (unencrypted). The number
must be in pure numeric format with no special characters.

encrdata

Encrypted parameters and values are sent in query parameters / payload.

Parameters and values to be passed in encrdata. Please note both the parameter and its value should be
encrypted.

Parameter

Value

Description

method

TWO_FACTOR_AUTH

The method for performing a specific action i.e. send an OTP SMS.
Parameter and its value must be sent in encrypted format. Encrypted
string should be URL encoded before sending it.

v

1.1

The default version is 1.1 and must be passed. Parameter and its value
must be sent in encrypted format. Encrypted string should be URL
encoded before sending it.

Phone_no

Phone no. of the
receiver

The number must be in the pure numeric format with no special characters, and should include the country code and mobile number of the recipient. Parameter and its value must be sent in encrypted format. Encrypted string should be URL encoded before sending it.

msg

UrlEncoded string of
UTF-8 characters

The message that needs to be sent. It can contain alphanumeric & special characters. The message must contain %code%. Parameter and its value must be sent in encrypted
format. Encrypted strings should be URL encoded before sending it.

msg_type

Text or Unicode_text

Indicates the type of the message to be sent. The default is “text”.
Parameter and its value must be sent in encrypted format. Encrypted
strings should be URL encoded before sending it.

format

TEXT, XML, JSON

Specific format for API response message. Parameter and its value
must be sent in encrypted format. Encrypted strings should be URL
encoded before sending it.

otpCodeLength

Numeric

This is the length of an OTP. It must be a positive integer less than or
equals to 10. Parameter and its value must be sent in encrypted
format. Encrypted strings should be URL encoded before sending it.

otpCodeType

NUMERIC,
ALPHABETIC or
ALPHANUMERIC

This parameter specifies a type of OTP. 3 values are permitted
NUMERIC (only numbers), ALPHABETIC (only alphabets),
ALPHANUMERIC (mix of numbers and alphabets). Parameter and its
value must be sent in encrypted format. Encrypted strings should be
URL encoded before sending it.

otp_code

OTP to be verified

The API verifies OTP if given otherwise sends OTP (This is the only
difference between Send OTP and Verify OTP). Parameter and its
value must be sent in encrypted format. Encrypted strings should be
URL encoded before sending it.

Sample Request

A sample request for “Generate and Send OTP + Verify OTP API” with encrypted data in the API payload looks like
this.

https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=xxxxxxxx&encrdata={{Base64 Encoded Encrypted Data}}
Generate and send OTP SMS:
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=xxxxxxxx&encrdata=
VEYcNxNQQcZ0t6VcfxZwzTpeTmBb0UKPYORWA1_VEIaGWrg7zS6aOdUYvmXCpOZbyGs2w9xKA_c43r0OnrL3KHUgUr
vIY1_5e-Om8y5zoWyCaWbV2OKFpa5yZQe0GQrm8PZyBJ-YIDgE7qswrrPj005nZZyFiCtDP50UDnaeg6RTVKV748lkURa1RDcs3lMkh3n5UsaNM5TU_lhkC0yreyuuNu8mlRQmNFDMUMWOfvNvhLL_H4
where
encrdata=
{{password=XXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX&msg=Your%20OTP%20code%
20is%20%25code%25&format=text&otpCodeLength=4&otpCodeType=NUMERIC}}
Verify OTP API:
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=xxxxxxxx&encrdata=
2qrYFF2dZpT1kLC9iFlfv2mdJgbtUntUuXtRj_Yz5-tVw3JDUNgvGIBHZFQMtJjNsMQwGEV6WZ3uFQPGdGYeVV43Ah3u82BVGO8naTea_Dbw1WbDd-cwc1uoGN8ip14suC6fEOJE2oz7Gy0
where
encrdata= {{password=XXXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX&otp_code=1564}}

The API response format is the same as the unencrypted payload. The output of encardata will be different every time as the IV (Initialization Vector) value will be unique for every request.

Please note that the “userid” parameter is mandatory and its value is to be sent in unencrypted format. All the other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded using the key.

You must use the key generated for your enterprise account to encrypt API parameter values when sending the API
request. Once the request is received by Gupshup, the payload is decrypted by Gupshup and sent ahead to the operator.


Did this page help you?