Table of Contents

OTP User Authentication (One time Password)

You are here:
< All API Documentations

1. Principles

With “Challenge” API, Bizao lets you authenticate the end-user using a PIN-CODE.
The end-user will receive the PIN via SMS. This code has 15mn duration. Two steps
are required to fulfill this authentication :

  • STEP 1

Generate Challenge to get a challenge ID based on the end-user’s MSISDN.
The PIN-CODE is sent at this stage.

  • STEP 2

Validate Challenge to generate a BIZAO_TOKEN and a BIZAO_ALIAS based
on the challenge ID you received in step01. The end-user will then be
authenticated

Sample of challenge ID :

“N2xe7xzk25FZEnS0YgmlD10a”

2. Generate Challenge

To generate Challenge you will use:

  • Bizao-URI :

/challenge/v1/challenges

  • Bizao-Host :

api.bizao.com

Your query will contain the Headers below :

HeaderDescription/Content
Content-Typeapplication/json
AuthorizationYOUR_ACCESS_TOKEN

The body of your query will contain the parameters below into a “challenge” object (JSON) :

ParameterUsageDescription
methodMandatoryAlways : OTP-SMS-AUTH
countryMandatoryISO 3166 alpha 3 country code. You can use the site below to
look for country code:
https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
serviceMandatoryAlways : BIZAO
partnerIdMandatoryAlways: PDKSUB
inputsMandatory
– MSISDN: end-user MSISDN
– confirmationCode: empty at this stage
message: authorized template
French -> “Pour confirmer votre achat XXXXX merci
d’entrer le code : %OTP%”
English -> “Please confirm your purchase XXXXX using this
code: %OTP%”
%OTP% is mandatory.
160 characters maximum.
– optLength: always “4”
– senderName: firendly name displayed on end-user device
( size should not exceed 11 characters)

A sample request :

curl --location --request POST 'https://api.bizao.com/challenge/v1/challenges' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer e8103fb-87ec-3789-81af-4deaa8d4ff72'
\ --data-raw '{
"challenge": {
"method": "OTP-SMS-AUTH",
"country": "SEN",
"service": "BIZAO",
"partnerId": "PDKSUB",
"inputs": [{
"type": "MSISDN",
"value": "+22177xxxxxxx"
},
{
"type": "confirmationCode",
"value": ""
},
{
"type": "message", "value": "Test %OTP%" },
{
"type": "otpLength",
"value": "4"v
},
{
"type": "senderName",
"value": "BIZAO"
}]
}
}

Success challenge query response (header) :

HTTP/1.1 201 Created
Location: http://[HOST]/challenge/v1/challenges/5bc5f37f7370537a0fb9f0fc

3. Validate Challenge

To validate Challenge you will use :

  • Bizao-URI :

/challenge/v1/challenges/challenge ID

  • Bizao-Host :

api.bizao.com

You will use the same Header and Body parameters as previously except for the inputs
parameters :

ParameterUsageDescription
inputsMandatoryJSON array of {key,value} entries containing all the necessary
inputs to perform the challenge:
– MSISDN : end-user MSISDN
– confirmationCode: the OTP received by the end-user
– info: always “OrangeApiToken,ise2” as value

A sample request :

curl --location --request POST 'https://api.bizao.com/challenge/v1/challenges/5f7310937970fd01a14d84f2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer e81pb-87ec-3789-81af-4deaa8d4ff72' \
--header 'Cookie: SERVERID=s1' \
--data-raw '{
"challenge": {
"method": "OTP-SMS-AUTH",
"country": "SEN",
"service": "BIZAO",
"partnerId": "PDKSUB",
"inputs": [{
"type": "MSISDN",
"value": "+22177xxxxxxx"
},
{
"type": "confirmationCode",
"value": "4130"
},
{
"type": "info",
"value": "OrangeApiToken,ise2"
}]
}
}'

Success validate challenge response :

Important : “OrangeApiToken” refers to BIZAO_TOKEN in your future calls and “ise2” to
BIZAO_ALIAS. The value of these 2 types may change in the next BIZAO API version
and becoming more generic.

{
"challenge": {
"method": "OTP-SMS-AUTH",
"result": [
{
"type": "OrangeApiToken",
"value":
"B64n0+sK4nkhwJ1cJh7wrWarjIGDvAm6KPVY4DKnFW3IQZYf82CdCaSso92tFKSFbjy7j+oE88h
G+PYcZrece3DxA==|MCO=OSN|tcd=1601376898|ted=1601376998|1sALKeLlaU3m6q69a5
/6uBYnxps="
},
{
"type": "ise2",
"value": "PDKSUB-200-SSTtmm0TCmd8BOqoxCEqfI/DpkGcHDG3x3ij5e6tpQ="
}
],
"country": "SEN",
"service": "BIZAO",
"partnerId": "PDKSUB",
"inputs": [
{
"type": "MSISDN",
"value": "+22177xxxxxxx"
},
{
"type": "confirmationCode",
"value": "4130"
},
{
"type": "info",
"value": "OrangeApiToken,ise2"
}
]
}
}

4. Recap of specific API-Challenge parameter value by authorized country

Below a recap of the specific API-Challenge parameters value by authorized country.

CountryCountry-Code
Ivory-CoastCIV
RDCongoCOD
CameroonCMR
SenegalSEN
TunisiaTUN
Burkina FasoBFA

5. OTP Authentication error

The following table lists the common error codes end messages that can be generated by
the Bizao platform :

HTTPCode
Status
and
CodeMessageDescription
400 Bad request232740000Missing inputThe following input is
missing: [input name]
400 Bad request232740001Malformed request body
400 Bad request232740003Invalid input valueThe following input is
invalid: [input name]
405 Method not
supported
N/AN/AN/A
500 Internal Server
error
232740004Internal Error[Complementary
information]
404 Not Found232740200Resource not foundUnknown challengeId
403 Forbidden232740201Authorization denied
403 Forbidden232740202Too many retries
400 Bad request232740203The provided challenge
inputs are invalid
[Complementary
information]
400 Bad request232740203Invalid Content-TypeError on JSON parameters

Next 3G User Authentication (Redirect URL)