API Integration

With the Hubtel Authentication service, the API Integration option allows engineers to seamlessly verify a user's identity directly via the API without utilizing the authentication system's UI. This method provides greater flexibility and control over the authentication process, enabling custom implementations that can better fit the specific needs of your application.

Available APIs

OTP (One-Time Password) APIs

The OTP (One-Time Password) system is designed to enhance security by providing users with a temporary, unique code that must be entered to complete the authentication process. This system typically involves two main steps:

1. Sending the OTP: The server generates a unique OTP and sends it to the user via SMS, Email, WhatsApp etc. If the user does not receive the OTP, they can dial the USSD short code 713*2# to retrieve it.

2. Verifying the OTP: The user enters the received OTP into the application or website. The server then verifies the OTP to complete the authentication process.

• OTP Request Endpoints

The OTP (One-Time Password) request endpoints is used to send OTP codes to users for authentication or verification purposes.
Note: If the user does not receive the OTP, they can access it via the USSD short code *713*2#.

1. SMS OTP Request
   This endpoint is used to send OTP code via SMS to the provided phone number.

   • Endpoint: [BASE_URL]/api/otp/send
   • Request Body:

     {
       "phoneNumber": "233547469379",
       "deviceName": "Apple Mac 10.15 desktop",
       "location": "JRM9+4W Accra, Ghana",
       "lat": "5.6328192",
       "platform": "web",
       "playerId": "a1b2c3d4e5",
       "lng": "-0.180224",
       "countryCode": "GH",
       "appId": [APP_ID],
       "recaptureToken": "token12345"
     }

2. Email OTP Request
   This endpoint is used to send OTP code via email.

   • Endpoint: [BASE_URL]/api/email/send
   • Request Body:

     {
         "phoneNumber": "233547469379",
         "deviceName": "Apple Mac 10.15 desktop",
         "location": "JRM9+4W Accra, Ghana",
         "lat": "5.6328192",
         "platform": "web",
         "playerId": "a1b2c3d4e5",
         "lng": "-0.180224",
         "countryCode": "GH",
         "appId": APP_ID,
         "recaptureToken": "token12345"
     }

3. WhatsApp OTP Request
   This endpoint is used to send OTP code via Whatsapp.

   • Endpoint: [BASE_URL]/api/whatsapp/send

   • Request Body:

     {
       "phoneNumber": "233547469379",
       "deviceName": "Apple Mac 10.15 desktop",
       "location": "JRM9+4W Accra, Ghana",
       "lat": "5.6328192",
       "platform": "web",
       "playerId": "a1b2c3d4e5",
       "lng": "-0.180224",
       "countryCode": "GH",
       "appId": [APP_ID],
       "recaptureToken": "token12345"
     }

     • Parameter Description

       Parameter	Type	Required	Description
       phoneNumber	number	Yes	The user's phone number in international format.
       deviceName	strin	No	The name of the user's device
       location	string	Yes	A brief description of the purchase.
       lat	string	No	The latitude of the user's location
       lng	string	No	The longitude of the user's location
       platform	string	No	The platform from which the request is made (e.g., web, mobile).
       playerId	string	Yes	The ID of the player's device
       countryCode	string	Yes	The country code of the user's location.
       appId	string	Yes	The ID of the application making the request.
       playerId	string	No	The token for verifying the recapture.

• OTP Verification Endpoints

OTP (One-Time Password) verification endpoints are used to verify OTP sent to users via various channels such as SMS, email, or Whatsapp.

1. SMS OTP Verification
   This endpoint is used to verify OTP sent via SMS.

   • Endpoint: [BASE_URL]/api/otp/verify
   • Request Body:

   {
     "phoneNumber": "233547469379",
     "requestId": "request123",
     "otpCode": "123456",
     "email": "[email protected]",
     "appId": [APP_ID],
     "prefix": "+233"
   }

2. Email OTP Verification
   This endpoint is used to verify OTP sent via email.

• Endpoint: [BASE_URL]/api/email/verify
• Request Body:

{
  "phoneNumber": "233547469379",
  "requestId": "request123",
  "otpCode": "123456",
  "email": "[email protected]",
  "appId": [APP_ID],
  "prefix": "+233"
}

3. WhatsApp OTP Verification
   This endpoint is used to verify OTP sent via Whatsapp.

• Endpoint: [BASE_URL]/api/whatsapp/verify
• Request Body:

{
  "phoneNumber": "233547469379",
  "requestId": "request123",
  "otpCode": "123456",
  "email": "[email protected]",
  "appId": [APP_ID],
  "prefix": "+233"
}

• Parameter Description

  Parameter	Type	Required	Description
  phoneNumber	String	Yes	The user's phone number in international format.
  requestId	String	Yes	The ID of the OTP request.
  otpCode	String	Yes	The OTP code sent to the user.
  email	String	No	The user's email address.
  appId	String	Yes	The ID of the application making the request.
  prefix	String	Yes	The verification code prefix. eg. for verification code: AYDS-8544 the prefix here is AYDS