POST /api/v1/auth/verify-otp

CLIENT API

Description

Validate OTP and authenticate customer. This is the second step in the authentication flow. Upon successful OTP verification, a JWT token is returned along with customer points information.

Client API: This endpoint is hosted by the Client System. Bigcity Microsite calls this API when a customer submits their OTP.

Headers

Authorization required

Basic Authentication header. Format: Basic <base64(username:password)>

Content-Type

application/json

Parameters

customer_id required, type: string

The unique Customer ID.

otp required, type: string

The 6-digit OTP received on the registered mobile number.

reference_id required, type: string

The reference ID returned from the generate-otp API.

Example Request

{
  "customer_id": "CUST12345",
  "otp": "123456",
  "reference_id": "REF123456"
}

Example Response

{
  "status": true,
  "token": "jwt-token",
  "customer": {
    "customer_id": "CUST12345",
    "mobile": "98XXXXXX45"
  },
  "points_earned": 5000,
  "balance_points": 3500
}

Example of Error Response

{
  "status": false,
  "message": "Invalid OTP"
}

Response Fields

status type: boolean

Indicates whether the OTP verification was successful.

token type: string

JWT token for session authentication (only on success).

customer type: object

Customer information object.

customer.customer_id type: string

The unique Customer ID.

customer.mobile type: string

Masked mobile number.

points_earned type: number

Total points earned by the customer.

balance_points type: number

Available balance points for redemption.

Business Rules

  • OTP validity: 5 minutes
  • Maximum retry attempts: 3
  • OTP must expire after successful use
  • JWT token is issued for session management