Table of Contents

Notification

You are here:
< All API Documentations

1. Subscription notification

Two kind of notification are made by the subscription API :

o B2C-Notification: For each successful subscription, the endUSer will receive an
SMS with a message ( the wording of this msg to be committed with Bizao in Onboarding
steps ) to inform him that his subscription is successful.

Note :

1. The Dynamic SMS is not available yet on this flow

2. All SMS-Notif are sent by the MNO(MTN)

o B2B-Notification: The Bizao backend will also notify the SP’s BackEnd via the SP’s
CallBack URL. See notification sample below :

{
"meta":
{
"type": "renewal - notif",
"source": "mtn"
} ,
"Subscription - id": "41e8fde7 - d7e4 - 4967 - b078 - d3f17c193030",
"renewal - id": "240000304702003290501020011005",
"renewal - timestamp": "2020 - 03 - 29 06:01:23.000",
"renewal - status": "Successful",
"user - id": "2258576xxxx",
"product - id": "Product-id",
"service - id":"Service-id",
"amount - charged": "1",
"currency": "XOF",
"cou ntry - code": "ci"
}

Within this subscription-notification you will have the fields :

The meta data will let you know :

o The type of notification according to each flow: <subscription>, <unsubscription> or <renewal>.

o The <MNO> source of this notification.

The body with provide the fields :

o “subscription-id” : the same ID as Bizao sent you on the real time
response for the subscription query “235efa19-a645-4195-8597-4c48a15482df”,

o “subscription-status” : the final status of the ongoing subscription : “Successful” or “Failure“.

o “user-id”: the MSISDN of the user who made a subscription

o “product-id”: the product ID you target ( sample “22501220000029439”).

o service-id”: your Service ID you got from Bizao ( its unique per SP”).

o sp-id : the SP-Id provided in the incoming query.

o “periodicity”: The periodicity of the subscription if it’s daily, weekly or monthly.

(Sample “86400” for daily).

o “amount-charged”: the real amount charged for the user ( sample “100”)

o “currency” : the currency used ( sample : “XOF”)

o “Sub-startdate” : the real subscription date ( sample: “2019-11-28 15:31:07.000”),

o “country-code” : the country your target for this subscription ( sample “ci” for Ivory Coast)

o “state” : the correlation data you sent in the subscription quey.

2. Renewal notification

Idem as for Subscription flow, Bizao manage two type of notification for the renewal
flow:

o B2C-Notification : For each successful subscription, the endUSer will receive an
SMS with a message ( the wording of this msg to be committed with Bizao in Onboarding
steps ) to inform him that his subscription is successful.

Note :

1.The Dynamic SMS is not available yet on this flow.

2. All SMS-Notif are sent by the MNO(MTN).

o B2B-Notification : The Bizao BackEnd will also notify the SP’s BackEnd via the SP’s
CallBack URL.

See notification sample below :

{
"meta":
{
"type": "renewal - notif",
"source": "mtn"
} ,
"Subscription - id": "41e8fde7 - d7e4 - 4967 - b078 - d3f17c193030",
"renewal - id": "240000304702003290501020011005",
"renewal - timestamp": "2020 - 03 - 29 06:01:23.000",
"renewal - status": "Successful",
"user - id": "2258576xxxx",
"product - id": "Product-id",
"service - id":"Service-id",
"amount - charged": "1",
"currency": "XOF",
"cou ntry - code": "ci"
}

Within this renewal-notification, you will have the fields :

Notification Body with fields below :

o “Subscription-id”: the same ID as Bizao sent you on the real time response for the
subscription query “0d658cdd-caaa-40d2-a082-fe112f81aa71”,

o “renewal-id”: the id of the renewal transaction,

o “renewal-timestamp”: Timestamp of the renewal stransaction

o “renewal-status”: the final status of this renewal transaction (sample
:”Completed”),

o “user-id”: the MSISDN of the User,

o “product-id”: The Product Id of the involved for this renewal,

o “service-id”: your Service ID you got from Bizao ( its unique per SP”),

o “amount-charged”: The final amount charged, – “currency”: The currency,

o “country-code”: the country code

3. UnSubscription notification

Bizao will also notify the SP’s backend for each successful UnSubscription made per user.

Bizao will use a dedicated meta-data for this notification, that meta data will let you know :

o The type of notification according to each flow : <subscription>, <unsubscription> or <renewal>

o The <MNO> source of this notification.

Sample of the full notification :

{
"meta": {
"type": "unsubscription - notif",
"source": "mtn"
} ,
"UnSubscription - id": "55564763 - 6425 - 441 d - 95 ef - 34 a36971df5c",
"Unsubscription - status": "Completed",
"Subscription - id": "41e8fde7 - d7e4 - 4967 - b078 - d3f17c193030",
"Unsubscription - timestamp": "2019 - 11 - 28 15:27:08.000",
"user - id": "2257533xxx",
"service - id":"225012000025033",
"product - id": "22501220000029439",
"country - code": "ci",
"state": "xxx"
}

Available Country and Operator

Below the list of country and MNO where the subscription is available service is available for Bizao.

Within this table you will find the required code for country and operator to use in the
mobile-money query call.

4. DCB-Subscription API error code

  • Error format
{
"requestError": {
"serviceException": {
"messageId": "xxxxxx", // Id of error message
"text": "xxxx text message xxxx", // Wording of error
"variables": "xxxxxx text message xxxxxx : list of parameter involved xxx” // List of parameter involved in this error }}
}
  • Below a Sample of error response:
{
"requestError": {
"serviceException": {
"messageId": "SVC0004",
"text": "No valid addresses provided in message part %1",
"variables": "No valid operator endpoint for request headers. Invalid parameter
for country - code or mno - name or sp - id or product - id"
}
}
}
  • Table of API error code
Error codeDescription/MessageHTTP code
SVC0001text : “A service error occurred. Error code is %1” variables: no
operator – No valid operator service for the subscription
request
Invalid operator service – No valid operator service for the
subscription status request.
400
SVC0002text: “Invalid input value for message part %1”
variables:
No subscription plan exists (provisioning data not exists) – Invalid
request headers or subscription details not found.
400
SVC0004text: “No valid addresses provided in message part %1”
variables: invalid subscription id – Invalid subscription id in the
request url operator end point not found – No valid operator
endpoint for
request headers. Invalid parameter for country-code or mno-name or
sp-id or product-id
400
SVC0206text: “Mandatory input item missing from request part
%1″ variables: invalid sp-id – Missing the header sp-id
invalid product id – Missing the header product-id
invalid user id – Missing the header user-id invalid
state parameter – Missing the header state
400
SVC0270text: API request failed. The subscription/unsubscription was not
applied
500
any
messageid
not starting
with SVC i.e
00000001
Please refer BackEnd error codes and list below500