OTP User Authentication (One time Password)
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 :
| Header | Description/Content |
| Content-Type | application/json |
| Authorization | YOUR_ACCESS_TOKEN |
The body of your query will contain the parameters below into a “challenge” object (JSON) :
| Parameter | Usage | Description |
| method | Mandatory | Always : OTP-SMS-AUTH |
| country | Mandatory | ISO 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 |
| service | Mandatory | Always : BIZAO |
| partnerId | Mandatory | Always: PDKSUB |
| inputs | Mandatory | – 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 :
| Parameter | Usage | Description |
| inputs | Mandatory | JSON 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.
| Country | Country-Code |
| Ivory-Coast | CIV |
| RDCongo | COD |
| Cameroon | CMR |
| Senegal | SEN |
| Tunisia | TUN |
| Burkina Faso | BFA |
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 | Code | Message | Description |
| 400 Bad request | 232740000 | Missing input | The following input is missing: [input name] |
| 400 Bad request | 232740001 | Malformed request body | |
| 400 Bad request | 232740003 | Invalid input value | The following input is invalid: [input name] |
| 405 Method not supported | N/A | N/A | N/A |
| 500 Internal Server error | 232740004 | Internal Error | [Complementary information] |
| 404 Not Found | 232740200 | Resource not found | Unknown challengeId |
| 403 Forbidden | 232740201 | Authorization denied | |
| 403 Forbidden | 232740202 | Too many retries | |
| 400 Bad request | 232740203 | The provided challenge inputs are invalid | [Complementary information] |
| 400 Bad request | 232740203 | Invalid Content-Type | Error on JSON parameters |