Mobitel Subscription as a Service API

The subscription as a service API lets developers use carrier billing based subscriptions. This is one of the APIs available in the Inzpire developer portal at https://developer.mobitel.lk/mobext/mapi/product. Similar to other APIs you have to create an application key in order to consume this API.

Step 1: Create an application key in API manager

To create an application click on 'Apps' link on the API portal and click on 'Create new App' on the top. Fill the following details to create the application

• Title - name of your application
• Description- brief description on what your app will do
• OAuth Redirect URI - The redirect URI used in oAuth flow if your application uses oAuth based authorization in any of the APIs.

• You can view your newly created app under 'Apps' and click on the app name to view further details. Note the ClientID in the and click the 'show' checkbox to view the ClientID. You will need this in consuming the APIs below
• Go to the API product page here and select the Subscription Management API,

• Click on the 'Subscribe' button and select the the application that you just created on the menu that pops up. Now your app is subscribed to the Subscription Management API

Step 2: Request a product ID

In this step you are expected to send a request informing us about the nature of the product you are going to let your customers subscribe to. This step is a manual process due to certain regulatory guidelines that should be adhered to. Send an email to inzpire@Mobitel.lk with the following details:

• Product name
• Charging amount
• Charging cycle (eg: daily, monthly)
• Short description of the product
• Your username in Inzpire developer portal

Once approved by the administrator, you will receive a product ID which can be used in the following steps for API invocation.

Step 3: Create subscription

The subscription management API exposes the following services:

• Add subscription - 
• Call this service to initiate a subscription process for the customer. 
• This will send a USSD popup to the customer requesting to approve the subscription for the product. The USSD popup will indicate the product name, the amount that will be charged and the charging cycle. 
• If the user accepts the prompt by entering 'S' and charging is successful, a subsequent call to the check subscription service will indicate that there is a valid subscription for the customer for that product.
• If the customer does not respond to the USSD or if the customer does not receive the USSD prompt due to any reason, you should call this service again after 2 minutes to re-initiate the process.
• Check subscription - This service will give a response indicating the subscription status of a customer to a product. 
• Remove subscription - This service will remove a user's subscription to a product.

3.1 API definition - Add subscription

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/subscription/addSubscription
• Request type:
• HTTP POST
• Headers:
• x-ibm-client-id : The application's client ID
• Body: The body should be a JSON formatted string with the following parameters
• productId: The product ID shared with you by the administrator upon creation of the subscription product on the platform end.
• customerNo: The customer mobile number from which the amount should be charged for this subcription
• eg: {"productId":"21","customerNo":"0712755777"}
• Response: received as a JSON formatted string with the following parameters
• reference: reference number of the transaction. Useful for logging and tracking puporses
• message: verbose response message
• status: response code

3.2 API definition - Check subscription

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/subscription/checkSub
• Request type:
• HTTP POST
• Headers:
• x-ibm-client-id : The application's client ID
• Body: The body should be a JSON formatted string with the following parameters
• productId: The product ID shared with you by the administrator upon creation of the subscription product on the platform end.
• customerNo: The customer mobile number 
• eg: {"productId":"21","customerNo":"0712755777"}
• Response: received as a JSON formatted string with the following parameters
• productId - the ID of the product that the customer is subscribed to
• orgName - the organization ID of the developer who is the product owner
• amount - charge amount
• planType - charging cyle (eg: daily, monthly)
• autoRenewal - indicates whether the subscription will be automatically renewed after the end of the period. This is enabled by default
• customerNo - The mobile number of the customer
• cusPackage - Customer package type (eg: prepaid/postpaid)
• expiresOn - subscription expiration date
• status - subscription status
• addedOn - subscription created date
• updatedOn - last charged date for the subscription
• terminatedOn - if the subscription is terminated, the termination date

3.3 API definition - Remove subscription

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/subscription/unSubscribe
• Request type:
• HTTP POST
• Headers:
• x-ibm-client-id : The application's client ID
• Body: The body should be a JSON formatted string with the following parameters
• productId: The product ID shared with you by the administrator upon creation of the subscription product on the platform end.
• customerNo: The customer mobile number
• eg: {"productId":"21","customerNo":"0712755777"}
• Response: received as a JSON formatted string with the following parameters
• reference: reference number of the transaction. Useful for logging and tracking puporses
• message: verbose response message
• status: response code

Great! Now you have all the details needed to add carrier billing based subscription charging for your application. Start exploring the API in the API console here