Generate OTP

Generate a One-Time Password (OTP) and deliver it to a user through SMS, Email, or both.

This API generates an OTP and returns an OTP UUID, which must be supplied when calling the Validate OTP API.

Endpoint

POST /v1/relid-otp

Authentication

Authorization: Bearer <access_token>

Request Body

Example Request

{
  "userId":"u1",
  "otpSpecs":[{"length":6,"charSets":"N","minNumeric":6,"exclude":["0","1"]}],
  "dispatchOptions":{"SMS":"smsTemplate1","EMAIL":"emailTemplate1"},
  "dynamicMacros":{"__CUSTOMER_NAME__":"John Doe","__AMOUNT__":"INR 2000"},
  "attempts":5,
  "expiresIn":300,
  "hashSpec":"SHA_256",
  "msgId":"payment-12345",
  "generateJwt":true
}

Field Details

dispatchOptions

Specify one or both channels.

{
  "SMS":"smsTemplate1",
  "EMAIL":"emailTemplate1"
}

dynamicMacros

Mandatory field, key/value pairs used to replace custom macros in the configured template.

If none then pass value as

eg: {"__CUSTOMER_NAME__":"John Doe","__AMOUNT__":"INR 2000"}

OTP Specifications (otpSpecs)

The otpSpecs field provides a flexible way to define the format and composition of an OTP. It is the recommended format for all new integrations.

Unlike the legacy otpSpec field, otpSpecs allows you to define multiple OTP segments, minimum character requirements, and excluded characters.

Structure

"otpSpecs": [
  {
    "length": 6,
    "charSets": "N",
    "minLowercase": 0,
    "minUppercase": 0,
    "minNumeric": 6,
    "minSpecial": 0,
    "exclude": ["0", "1"]
  }
]

Multiple specifications can be combined to create patterned OTPs.

"otpSpecs": [
  {
    "length": 2,
    "charSets": "U"
  },
  {
    "length": 4,
    "charSets": "N"
  }
]

This generates a 6-character OTP consisting of 2 uppercase letters followed by 4 digits.

Fields

length

• Minimum: 4
• Maximum: 12

Rules

• Each OTP segment must have a length between 4 and 12.
• The combined length of all segments must also be between 4 and 12.

Valid Example

"otpSpecs": [
  { "length": 4 },
  { "length": 5 }
]

Invalid Example – Segment Too Long

"otpSpecs": [
  { "length": 15 }
]

Invalid Example – Total Length Too Long

"otpSpecs": [
  { "length": 4 },
  { "length": 10 }
]

charSets

Supported special characters:

! @ # $ % & * - _ =

Character set combinations include NU, LN, UN, MN, US, LS, MS, UNS, LNS, and MNS.

Rules

• Use only supported character set identifiers.
• Do not repeat character set identifiers.

Valid: NU, US, LNS

Invalid: P, X, NNU

Minimum Character Requirements

These fields apply only when the corresponding character set exists in charSets.

• minLowercase
• minUppercase
• minNumeric
• minSpecial

Rule

The sum of all minimum character requirements must not exceed the configured length.

Valid Example

{
  "length": 4,
  "minLowercase": 1,
  "minUppercase": 1,
  "minNumeric": 1,
  "minSpecial": 1
}

Invalid Example

{
  "length": 4,
  "minLowercase": 2,
  "minUppercase": 1,
  "minNumeric": 1,
  "minSpecial": 1
}

exclude

Use exclude to prevent specific characters from appearing in the generated OTP.

"exclude": ["0", "1", "I", "O"]

Best Practices

• Prefer otpSpecs over the legacy otpSpec.
• Exclude visually similar characters such as 0, O, 1, and I.
• Validate that the total OTP length is between 4 and 12 characters.

otpSpec (Legacy)

Legacy OTP specification format.
Supported OTP specifications are:

• N-x
• L-x
• U-x
• M-x
• LN-x
• UN-x
• MN-x

Where,

• L – Lowercase alphabets,
• U – Uppercase alphabets,
• M – Mixed case alphabets,
• N – Numeric characters,
• LN – Lowercase alphabets and Numeric characters,
• UN – Uppercase alphabets and Numeric characters,
• MN – Mixed case alphabets and Numeric characters
• x – the length of OTP value to be generated. Minimum 4, Maximum 9.

Examples:

• N-6
• L-6
• U-6
• M-6
• LN-6
• UN-6
• MN-6

Please note that the character set and length is separated by the hyphen "-". The OTP specification followed by default is “N-6”, indicating that the OTP should consist of 6 characters and be generated solely from numeric characters.

Backward Compatibility

Supported Hash Algorithms

• PLAIN
• SHA_256
• SHA_384
• SHA_512
• SHA_HEX_256
• SHA_HEX_384
• SHA_HEX_512

Success Response

{
  "otpUuid":"6c677c1e-e78e-4e19-a77c-1ee78efe1998"
}

Error Responses

Best Practices

• Prefer otpSpecs for new integrations.
• Store the returned otpUuid.
• Include __RELID_OTP__ in every OTP template.