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.www.bizao.com

• BIZAO-URI : challenge/v1/challenges

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 following link 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)
Sample Request :

curl -i -X POST \
https://api.www.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.www.bizao.com

Sample Request :

curl -i -X POST \
https://api.www.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.www.bizao.com

You query will contain the Mandatory Headers below:

HeaderDescription/Content
Bizao-aliasthe BIZAO-ALIAS that you should generate using one of Authentication method above
Bizao-tokenthe BIZAO-TOKEN that you should generate using one of Authentication method above
(OrangeApiToken in this current version of authentication).
AuthorizationYOUR_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 nameDescription/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.www.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

ErrorCodeException textVariables
POL0253Payment operation refused by usernone
POL0254 The amount exceeds the operator limit for a single Forbidden charge none
POL1000 User has insufficient credit for transaction none
POL1001The %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.
POL1002The charge happened too soon after the previous one none
POL1004Refund below minimum refundable amount supported %1%1 – the minimum refundable amount supported
POL1005A refund request requires the original Server Reference Code for the charge that is being refundednone
POL1006originalServerReference Code not validnone
POL2010Inconsistent transactionnone
POL2011Transaction expired or invalidnone
SVC0007Invalid charging informationnone
SVC0270Charging operation failed, the charge was not appliednone
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.www.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 :

HeaderDescription/Content
X-OAPI-Application-Idalways use: BIZAO
X-OAPI-Contact-Idalways use: b2b-bizao-97b5878
X-OAPI-Resource-Typealways use: SMS_OSM
bizao-aliasBIZAO_ALIAS generated using one of the authentication method above (ise2 in this current version of authentication)
bizao-tokenBIZAO_TOKEN generated using one of the authentication method above. (OrangeApiToken in this current version of authentication)
X-Orange-MCOOxx , 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”
AuthorizationYOUR_ACCESS_TOKEN

The body of your query will contain the parameters below :

ParameterDescription
addressRecipient 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
messageString, 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
SenderNameFirendly name displayed on end user device ( size should not exceed 11 characters)
clientCorrelatorString, 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.
receiptRequestnotifyURL: 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
callbackDataallbackData: 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.www.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.

CountryMCOsenderAddress
Ivory- CoastOCItel:+2250000
RDCongoODC tel:+2430000
CameroonOCM tel:+2370000
SenegalOSNtel:+2210000
TunisiaOSN tel:+2160000
Burkina fasoOBFTel:+2260000

4. Notification error codes

SVC0280Message too long. Maximum length is %1 characters%1 – number of characters allowed in a message400 Bad request
900908Resource forbiddennone403 Forbidden

SMS API internal error codes

InternalOutput mapping
Error codeDescriptionError codeError Variables
PDK_SMSW_0001Internal errorSVC0001%1: PDK_SMSW_0001
PDK_SMSW_0002Integration errorSVC0001%1: PDK_SMSW_0002
PDK_SMSW_0003Unavailable countrySVC0004%1: senderAddress value
PDK_SMSW_0004Duplicate client correlatorSVC0004%1: clientCorrelator value
%2: TBD
PDK_SMSW_0005Missing input valueSVC0002%1: missing value
PDK_SMSW_0006Invalid sender addressSVC0004%1: senderAddress value
PDK_SMSW_0007Invalid recipient addressSVC0004%1: address value
PDK_SMSW_0008Message too longSVC0280%1: max message length
PDK_SMSW_0009Invalid input valueSVC0002%1: invalid value
PDK_SMSW_0011BE-API is unresponsiveSVC0001%1: PDK_SMSW_0011
PDK_SMSW_0013SDP GOS is unresponsiveSVC0001%1: PDK_SMSW_0013
PDK_SMSW_1000BE-API internal errorSVC0001%1: PDK_SMSW_1000
PDK_SMSW_1001Resource consumption failure: not authorized [%1]POL0001%1: Not enough credit
PDK_SMSW_1002Resource consumption failure: invalid parameterPOL0001%1: No contract found for the given country / service / contact
PDK_SMSW_1003Resource consumption failure: not authorized [%1]POL0001%1: Expired contract
PDK_SMSW_1004Resource consumption failure: unknown transaction IDSVC0001%1: PDK_SMSW_1004
PDK_SMSW_3000SDP GOS internal errorSVC0001%1: PDK_SMSW_3000
PDK_SMSW_3001SDP GOS SLA errorSVC0001%1: PDK_SMSW_3001 k
Retour en haut