Service Providers access to Bizao APIs
Bizao gateway gives you an access to a range of one-time REST API. It provides you end-points to process your business traffic with different Telco-operators in Africa.
To use the API, the service provider needs to sign-up and subscribe to Bizao API’s offers.
So far, the sign-up & subscription process is made off-line by the Bizao team, which will be on self-service basis for a future version of Bizao API (already on roadmap).
After subscription, the Bizao team will give you an ACCESS_TOKEN to use as Header in all calls you will make to the API:
Sample of ACCESS_TOKEN : “4qa1bae4-3f9b-346-9t8b-c0e4d4ef”
The B2B connection to the Bizao platform is made in SSL1 to secure your traffic
If the EndUser discover your service trought Orange APP MyPlace, The MyPlace will authenticate end-user with one of below method:
1.One Time Password (Mobile Connect):
This is a web explicit authentication mode. It is adapted for all HTTP access. It only needs a mobile to receive a PIN code by SMS.
2.3G-Redirect URL
This is a mobile implicit mode. It works only for MNOs customers connected through the 3G data network. The result of a successful authentication is sent to a callback URL provided by your app.
3. MO SMS with ShortCode:
This is an implicit mode. The authentication process starts by sending a SMS thanks to a short-code linked to a callback URL provided by your app.
The description and use of these methods are explained in dedicated sections within this document.
In the authentication journey, the Bizao platform will generate/provide you a pair of keys as credentials for each Client authenticated:
– BIZAO_TOKEN:
It’s a unique and limited time ID (1 year) to use for critical API calls such as payment API)
Sample of TOKEN : “B64ZNgw9MaNekCsFRYf9pe6WZFzYnOKQxoyUagq8v2anGGrY4JG+Xx5MO42 iFpkEYzf|MCO=OCI|tcd=1526548445|ted=1526348545|uSmSX85ScNIIMK5QH OK1kSoN”
Note: These Keys/ID are made unique by MSISDN and must be used instead of user’s MSISDN for all API calls you will made on the Bizao platform.
Your ACCESS_TOKEN
Main credentials
At subscription, the Bizao team will provide you:
– a valid Bearer ACCESS_TOKEN
OTP Authentication
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
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
Validate Challenge to generate a BASIC_TOKEN and BIZAO_ALIAS based on the challenge ID you received in Step 1.
The end-user will then be authenticated
Sample of challenge ID : 5bc5f37f7370537a0fb9f0fc
2. Generate challenge
To generate Challenge you will use:
• BIZAO-HOST : api.site-dev.bizao.com
• BIZAO-URI : challenge/v1/challenges
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 following link 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) |
Sample Request :
curl -i -X POST \
https://api.site-dev.bizao.com/challenge/v1/challenges/ \
-H ‘authorization: Bearer YOUR_ACCESS_TOKEN’ \
-H ‘cache-control: no-cache’ \
-H ‘content-type: application/json’ \
-d ‘
{
« challenge »: {
« method »: « OTP-SMS-AUTH »,
« country »: « CIV »,
« service »: « BIZAO »,
« partnerId »: « PDKSUB »,
« inputs »: [{
« type »: « MSISDN »,
« value »: « +22500000000 »
}, {
« type »: « confirmationCode »,
« value »: « »
}, {
« type »: « message »,
« value »: « Please confirm your purchase XXXXX using this code: %OTP% »
}, {
« type »: « otpLength »,
« value »: « 4 »
}, {
« type »: « senderName »,
« value »: « NameToDisplay »
}]
}
}’
Success Response on the header:
Only the information in the header response will be used to validate the OTP for next step.
HTTP/1.1 201 Created
Location: http://[HOST]/challenge/v1/challenges/5bc5f37f7370537a0fb9f0fc
3. Validate challenge
To validate Challenge you will use :
• BIZAO-URL : /challenge/v1/challenges/challenge_ID
• BIZAO-HOST: api.site-dev.bizao.com
Sample Request :
curl -i -X POST \
https://api.site-dev.bizao.com/challenge/v1/challenges/5bc5f37f7370537a0fb9f0fc \
-H ‘authorization: Bearer YOUR_ACCESS_TOKEN’ \ -H ‘cache-control: nocache’ \
-H ‘content-type: application/json’ \
-d ‘
{
« challenge »: {
« method »: « OTP-SMS-AUTH »,
« country »: « CIV »,
« service »: « BIZAO »,
« partnerId »: « PDKSUB »,
« inputs »: [{
« type »: « MSISDN »,
« value »: « +22500000000 »
},
{
« type »: « confirmationCode »,
« value »: « 9683 »
},
{
« type »: « info »,
« value »: « OrangeApiToken,ise2 »
}
]
}
} ‘
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 |
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=16013769
98|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 »,
« type »: « 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:
| Parameter | 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 | 232740002 | Malformed URI | |
| 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 | Invalid Resource not foundvalue | 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 |
Orange DCB Payment API
1. Principles
To Charge the End User, you first need to generate the user bizao-token and alias using one of three Authentication mechanims described previously.
Note : Payment/v2 is available in OCI/OCM/OBF/OSN/ODC/OML/OMA/OTN
2. Description
This payment method is a one-time API, we manage a new version of this API (v2) that are using bizao-alias in stread of bizao-token as for the v1 To charge your end user you will use:
• BIZAO-URI : /payment/v2/acr:X-Orange-ISE2/transactions/amount
• BIZAO-HOST : api.site-dev.bizao.com
You query will contain the Mandatory Headers below:
| Header | Description/Content |
| Bizao-alias | the BIZAO-ALIAS that you should generate using one of Authentication method above |
| Bizao-token | the BIZAO-TOKEN that you should generate using one of Authentication method above (OrangeApiToken in this current version of authentication). |
| Authorization | YOUR_ACCESS_TOKEN |
| mno-name | (string) the name of operator you targetexample : orange. Bizao will update you regarding the new mno set in the hub |
| country-code | (string)2 characters code of the country you target ( use this norme : ISO 3166 alpha 2 country code, url to get the all country-code list: https://www.iban.com/country-codes (for instance : <tn> is the country-code for Tunisia. |
| serviceID | (string) Always “BIZAO” |
| Sp-id | (string), the SP dedicated Service ID that Bizao will communicate you (Sample: <abcd>) |
| Product-id | (string) The SP dedicated product id that Bizao will communicate you (Sample: <abcd daily>) |
The body of your query will contain the parameters below :
| Parameter name | Description/Content |
| amount | (decimal) amount to be charged.Note : Please note that the currency code “USD” amount for DR Congo refers actually to Unit (U). It has the following ratio: 1 USD / 100 UNITS. |
| currency | (string) currency identifier as defined in [ISO4217]. Note (as described for the amount parameter) either currency and amount or code must be specified. you can use this site to know the currency-code by country: See currency-codes of countries |
| clientCorrelator | (string) uniquely identifies this create charge request. If there is a communication failure during the charge request. Using the same clientCorrelator when retrying the request allows the operator to avoid applying the same charge twice. This field SHOULD be present. |
| description | (string) description text to be used for information and billing text |
| endUserId | (string) Always acr:X-Orange-ISE2. |
| onBehalfOf | (string) allows aggregators/partners to specify the merchant-service name. Note : Must contains the same value as <SPNameServiceName > |
| transactionOperationStatus | (string) specifies the payment operation required. In this case set to ‘Charged’ according to the DCB Standard. |
Charge query sample:
Request sample :
curl –location –request POST ‘https://api.site-dev.bizao.com/payment/v2/acr%3AX-OrangeISE2/transactions/amount’ \
–header ‘authorization: Bearer 4d34d3bd-3acb-35c4-bd37-6050d9fd9650’ \
–header ‘cache-control: no-cache’ \
–header ‘Content-Type: application/json’ \
–header ‘bizao-token:
B64k0dOzE96eo1laO9xEqyAQ5dUmWXIgd289i7DTcn9G08rTDVdZWU4G5tfl3+F4e3Z|MCO=OCI|tcd=1563
480095|ted=1563480195|pBvsc7Jb1XycCnj88rgbz1iqBqQ=’ \
–header ‘bizao-alias: PDKSUB-200-0nNZkFpbougrL2KQQTQVKpvO7f/mmOO816X5txYKzOA=’ \
–header ‘country-code: ci’ \
–header ‘mno-name: orange’ \
–header ‘sp-id: Bright Mobile’ \
–header ‘product-id: Viddigo daily CI’ \
–header ‘Cookie: SERVERID=s0’ \
–data-raw ‘{
« amountTransaction »: {
« endUserId »: « acr:X-Orange-ISE2 »,
« paymentAmount »: {
« chargingInformation »: {
« amount »: « 0.1 »,
« currency »: « XOF »,
« description »: « Viddigo daily wen »
},
« chargingMetaData »: {
« onBehalfOf »: « Bright Mobile – Viddigo »,
« serviceId »: « BIZAO_HYB »
}
},
« transactionOperationStatus »: « Charged »,
« clientCorrelator »: « Ref-5561234 »,
« antifraudId »: »123456789″
}
}’
Note :
For each new payment-query you have to set a new value for “clientCorrelator” parameter otherwise the Bizao BackEnd will not handle a new payment on this user
Success Response Sample :
{
« amountTransaction »: {
« endUserId »: « acr:OrangeAPIToken »,
« paymentAmount »: {
« chargingInformation »: {
« description »: « MYProduct « ,
« currency »: « TND »,
« amount »: 0.01
},
« totalAmountCharged »: 0.01,
« chargingMetaData »: {
« onBehalfOf »: « Viddigo daily « ,
« serviceId »: « BIZAO »
}
},
« transactionOperationStatus »: « Charged »,
« referenceCode »: « abtx-3333HR-xpoaqs-xxxxxxxxxx »,
« serverReferenceCode »: « 388bcd04-8a97-416d-8390-d54afabad346 »,
« clientCorrelator »: « Ref-5561234 »,
« resourceURL »: « https://gateway1a.mife.slamobile.com.my:8243/payment/v1/acr%3AOrangeAPIToken/transactions/amount/15421354654538P
A158065263″
}
}
Important : If you receive a success response but with the same “serverReferenceCode” it means that you already attempted to charge with the same « clientCorrelator ». In that case your charging request won’t get through.
3. Payment error code
| ErrorCode | Exception text | Variables |
| POL0253 | Payment operation refused by user | none |
| POL0254 | The amount exceeds the operator limit for a single Forbidden charge | none |
| POL1000 | User has insufficient credit for transaction | none |
| POL1001 | The %1 operator charging limit for this user has been exceeded | %1 – the time period for which the charging limit has been reached, e.g. hourly daily, weekly, monthly. |
| POL1002 | The charge happened too soon after the previous one | none |
| POL1004 | Refund below minimum refundable amount supported %1 | %1 – the minimum refundable amount supported |
| POL1005 | A refund request requires the original Server Reference Code for the charge that is being refunded | none |
| POL1006 | originalServerReference Code not valid | none |
| POL2010 | Inconsistent transaction | none |
| POL2011 | Transaction expired or invalid | none |
| SVC0007 | Invalid charging information | none |
| SVC0270 | Charging operation failed, the charge was not applied | none |
SMS MT Notification API
1. Principles
Bizao provides you with a free SMS-Bundle to let you notify your end user using the SMS API. To notify the end_user, youfirst need to generate the user’s bizao-token and bizao-alias using one of three authentication mechanims described previously.
2. Description
To notify your end-user by SMS, you will use :
• BIZAO-URI : smsmessaging/v1/outbound/tel%3A%2Bxxxxx/requests
• BIZAO-HOST : api.site-dev.bizao.com
where : “tel%3A%2Bxxxxx” is your sender-address in url encode format.
Sample : “tel%3A%2B2250000”
The query will contain the Headers set to the specified value below :
| Header | Description/Content |
| X-OAPI-Application-Id | always use: BIZAO |
| X-OAPI-Contact-Id | always use: b2b-bizao-97b5878 |
| X-OAPI-Resource-Type | always use: SMS_OSM |
| bizao-alias | BIZAO_ALIAS generated using one of the authentication method above (ise2 in this current version of authentication) |
| bizao-token | BIZAO_TOKEN generated using one of the authentication method above. (OrangeApiToken in this current version of authentication) |
| X-Orange-MCO | Oxx , where xx is an alpha2 country code. You can use this site to got this code: “https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2” |
| Authorization | YOUR_ACCESS_TOKEN |
The body of your query will contain the parameters below :
| Parameter | Description |
| address | Recipient user ID is a key in the header which contains the end user alias to use. Authorized values are: acr:X-Orange-ISE2 for the header X-Orange-ISE2 |
| message | String, must be URL-escaped as per RFC 1738 and not longer than 160 characters. |
| senderAddress (*) | String, See 5.3 Recap of API-SMS parameter for values |
| SenderName | Firendly name displayed on end user device ( size should not exceed 11 characters) |
| clientCorrelator | String, Uniquely identifies this created SMS request. This will be useful in communication String, failures while sending the request. By using the same clientCorrelator when retrying the request WSO2.TELCO HUB avoids sending the same SMS again. |
| receiptRequest | notifyURL: String, The URL to which you would like a notification of delivery sent. The format of this notification is shown below. If notifications are required the notifyURL parameter will be sent within the receiptRequest element |
| callbackData | allbackData: Will be passed back in this notification. It’s used to identify the message the receipt relates to (or any other useful data, such as a function name). This is only valid if notifications are required – sent with the notifyURL parameter within the receiptRequest element |
SMS Notification query sample:
Note: For more detail you can see the swagger file: “BIZAO-SMS_V1_swagger.yaml”
Request sample :
curl -X POST \
https://api.site-dev.bizao.com/smsmessaging/v1/outbound/tel%3A%2B2250000/requests \
-H ‘authorization: Bearer YOUR_ACCESS_TOKEN’ \
-H ‘cache-control: no-cache’ \
-H ‘content-type: application/json’ \
-H ‘bizao-token: BIZAO_TOKEN’ \
-H ‘x-oapi-application-id: BIZAO’ \
-H ‘x-oapi-contact-id: b2b-bizao-97b5878’ \
-H ‘x-oapi-resource-type: SMS_OSM’ \
-H ‘bizao-alias: BIZAO_ALIAS’ \
-H ‘x-orange-mco: OCI’ \
-d ‘ {
« outboundSMSMessageRequest »: {
« address »: [« acr:X-Orange-ISE2 »],
« senderAddress »: « tel:+2250000 »,
« outboundSMSTextMessage »: {
« message »: « Welcome SMS »
},
« clientCorrelator »: « MyCorrealtorID »,
« receiptRequest »: {
« notifyURL »: « http://application.example.com/notifications/DeliveryInfoNotification »,
« callbackData »: « some-data-useful-to-the-requester »
},
« senderName »: « NameToDisplay »
}
}
Note : For each new SMS-Query you have to provide a new “clientCorrelator” value SMS
Success response sample:
{
« outboundSMSMessageRequest »: {
« address »: [
« acr:X-Orange-ISE2 »
],
« senderAddress »: « tel:+2210000 »,
« senderName »: « BIZAO »,
« receiptRequest »: {
« notifyURL »: « http://application.example.com/notifications/DeliveryInfoNotification »,
« callbackData »: « some-data-useful-to-the-requester »
},
« outboundSMSTextMessage »: {
« message »: « Votre abonnement a réussi. »
},
« clientCorrelator »: « MyCorrealtorID »,
« resourceURL »: « https://gateway1a.mife.sla-mobile.com.my:8243/smsmessaging/outbound/tel%3A%2B2210000/requests/1529584291923SM8202/ deliveryInfos »
}
}
3. Recap of API-SMS parameter value by authorized country
Below a recap of specific API-SMS parameter value by authorized country.
| Country | MCO | senderAddress |
| Ivory- Coast | OCI | tel:+2250000 |
| RDCongo | ODC | tel:+2430000 |
| Cameroon | OCM | tel:+2370000 |
| Senegal | OSN | tel:+2210000 |
| Tunisia | OSN | tel:+2160000 |
| Burkina faso | OBF | Tel:+2260000 |
4. Notification error codes
| SVC0280 | Message too long. Maximum length is %1 characters | %1 – number of characters allowed in a message | 400 Bad request |
| 900908 | Resource forbidden | none | 403 Forbidden |
SMS API internal error codes
| Internal | Output mapping |
| Error code | Description | Error code | Error Variables |
| PDK_SMSW_0001 | Internal error | SVC0001 | %1: PDK_SMSW_0001 |
| PDK_SMSW_0002 | Integration error | SVC0001 | %1: PDK_SMSW_0002 |
| PDK_SMSW_0003 | Unavailable country | SVC0004 | %1: senderAddress value |
| PDK_SMSW_0004 | Duplicate client correlator | SVC0004 | %1: clientCorrelator value %2: TBD |
| PDK_SMSW_0005 | Missing input value | SVC0002 | %1: missing value |
| PDK_SMSW_0006 | Invalid sender address | SVC0004 | %1: senderAddress value |
| PDK_SMSW_0007 | Invalid recipient address | SVC0004 | %1: address value |
| PDK_SMSW_0008 | Message too long | SVC0280 | %1: max message length |
| PDK_SMSW_0009 | Invalid input value | SVC0002 | %1: invalid value |
| PDK_SMSW_0011 | BE-API is unresponsive | SVC0001 | %1: PDK_SMSW_0011 |
| PDK_SMSW_0013 | SDP GOS is unresponsive | SVC0001 | %1: PDK_SMSW_0013 |
| PDK_SMSW_1000 | BE-API internal error | SVC0001 | %1: PDK_SMSW_1000 |
| PDK_SMSW_1001 | Resource consumption failure: not authorized [%1] | POL0001 | %1: Not enough credit |
| PDK_SMSW_1002 | Resource consumption failure: invalid parameter | POL0001 | %1: No contract found for the given country / service / contact |
| PDK_SMSW_1003 | Resource consumption failure: not authorized [%1] | POL0001 | %1: Expired contract |
| PDK_SMSW_1004 | Resource consumption failure: unknown transaction ID | SVC0001 | %1: PDK_SMSW_1004 |
| PDK_SMSW_3000 | SDP GOS internal error | SVC0001 | %1: PDK_SMSW_3000 |
| PDK_SMSW_3001 | SDP GOS SLA error | SVC0001 | %1: PDK_SMSW_3001 k |
