Introduction

The Billing Platform API can be used to access various mobile operator billing related services, such as subscribing and unsubscribing customers for your web app.

The Billing Platform API has a set of GET and POST endpoints, and responds with JSON or HTML responses.

The API is authenticated using JWT (JSON Web Tokens), and provides a complete list of endpoints to obtain, check and refresh tokens. Your app will need to authenticate each request with the authentication tokens provided through the authentication process.

Setup

Each app will be provided with a unique set of credentials with which the Billing Platform API can be accessed, along with additional keys required for accessing various API functions.

Required from you

You will need to provide us the following:

• App name
• Home page URL
• Callback URL (see Callbacks)
• Maximum inactive days before a user is suspended (default is 30 days)

Redirection pages / URLs

For some APIs, a redirection URL is required (eg. Subscribe). These URLs (referred to as pages) need to be setup on the Billing Platform API beforehand by us. A default redirection page will be setup, alongside any number of other pages as required. The below fields will be setup on the Billing Platform API for each page:

• Page URL (provided by You)
• Unique code (provided by us)

When a request that requires redirection back to the app is sent, the unique code for the page should be set as the page parameter.

Provided by us

We will provide you the following:

Customer Management

The Billing Platform API provides a set of endpoints to manage the entire customer lifecycle. The process for obtaining a customer is as follows:

1. Subscribe a new customer
2. Record the new customer's subscription details returned from the API
3. (Optional) Periodically check the customer's status

Customer lifecycle

A customer may have only one active subscription per app per mobile network. The subscription will be for a package (daily, weekly, monthly etc) that is setup by us.

Each subscription will go through multiple states during the customer lifecycle.

Subscription statuses

Managing the customer lifecycle

Below is an example of how the customer lifecycle is commonly managed via the Billing Platform API.

1. When a customer lands on your home page, redirect them to the Get Customer endpoint and capture customer details.
2. Record the customer details on your end after the customer is redirected back to your app. In some cases (e.g. WiFi), the customer details will not be available, in which case you may need to ask the customer to enter their mobile number.
3. Check the customer's subscription status by either checking your own records or getting customer info from the Customer Info endpoint.
4. Show the customer subscribe buttons (one per active package) if the customer is not yet subscribed. If they are already subscribed, allow them to access your app content.
5. Redirect the customer to the Subscribe endpoint when they click on a subscribe button.
6. Wait for the Billing Platform API's Callbacks and update your records for the customer's subscription status.

API Response Formats

The Billing Platform API returns the parameters status, code and message with all responses.

Status

This will be either success or error.

Code

This will be one of the success or error response codes defined below.

Message

A description of the success or error scenario.

GET Requests

For GET requests, the Billing Platform API expects the customer to be redirected to the Billing Platform API with certain query parameters appended to the request. The Billing Platform API responds to GET requests by redirecting back to an app-specific pre-configured page. Appended query parameters on this redirect will contain the requested information.

Success redirect response example

HTTP/1.1 302 Found
Location: http://your-app.com?code=1000&status=success&message=<success description>&key=value

Error redirect response example

HTTP/1.1 302 Found
Location: http://your-app.com?code=<error code>&status=error&message=<error description>

Success responses

Success responses will redirect to the given page with requested details appended as query parameters.

Error responses

Error responses behave a little differently depending on the error encountered.

• Case A: If the Access-Token and page is required and provided, the response will be a redirection to the page, with error details appended as query parameters
• Case B: If the Access-Token is not provided or malformed, an error will be displayed
• Case C: If the page is required but not provided or malformed, the response will be a redirection to the default page for the app, with error details appended as query parameters
• Case D: If the default page has not been configured, an error will be displayed. This will rarely ever occur.

POST Requests

Success response example

HTTP/1.1 200 OK

{
  "status": "success",
  "code": 1000,
  "message": "<success description>"
}

Error response example

HTTP/1.1 422 Unprocessable Entity

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

The Billing Platform API responds to POST requests with a JSON response. Authentication tokens for authentication requests will be set in the response header. The Billing Platform API accepts data as raw JSON, form-data or x-www-form-urlencoded.

Response codes

The Billing Platform API uses the following response codes:

Authentication

The Billing Platform API uses JSON Web Token based authentication which simplifies the authentication process, which is as follows:

1. Login to the API using the provided credentials and obtain an Access Token and Refresh Token. The Access Token is valid for:
   • 1 day in production mode
   • 1 hour in development mode
2. Use the Access Token on subsequent API calls
3. Periodically refresh the Access Token by using the Refresh Token

The Billing Platform API also provides an endpoint to verify if the current Access Token is still valid.

Login

Request

POST /v1/auth/login

{
  "email": "<email>",
  "password": "<password>"
}

Success response

HTTP/1.1 200 OK
Access-Token: <access-token>
Refresh-Token: <refresh-token>
Expire-At: 1646839817

{
  "status": "success",
  "code": 1000,
  "message": "Signed in successfully"
}

Error response

HTTP/1.1 422 Unprocessable Entity

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Login to the Billing Platform API and create an authenticated session for your app.

Login flow

Request

The following parameters should be set as a JSON payload on the request body.

• email: Login email provided by us
• password: Login password provided by us

Response

Token information will be returned in the response headers.

• Access-Token: This token should be stored and sent with every request
• Refresh-Token: Used when refreshing the Access-Token (see Refresh Token)
• Expire-at: Unix timestamp for Access-Token expiry

Refresh Token

Request

POST /v1/auth/refresh_token
Authorization: Bearer <access-token>
Refresh-Token: <refresh-token>

Success response

HTTP/1.1 200 OK
Access-Token: Bearer <access-token>
Refresh-Token: <refresh-token>
Expire-At: 1546708020

{
  "status": "success",
  "code": 1000,
  "message": "Token refreshed successfully"
}

Error responses

HTTP/1.1 422 Unprocessable Entity

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Use the Refresh-Token to get a new Access-Token and Refresh-Token.

Refresh Token flow

Request

The following parameters should be set on the request header.

• Authorization: The current Access-Token preceded by Bearer
• Refresh-Token: The current Refresh-Token

Response

Token information will be returned in the response headers.

• Access-Token: This token should be stored and sent with every request
• Refresh-Token: Used when refreshing the Access-Token
• Expire-at: Unix timestamp for Access-Token expiry

Check Token

Request

POST /v1/auth/check_token
Authorization: Bearer <access-token>

Success response

HTTP/1.1 200 OK

{
  "status": "success",
  "code": 1000,
  "message": "Success"
}

Error responses

HTTP/1.1 401 Unauthorized

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Check if the Access Token is valid. This endpoint can be used to check the validity of a token to work out if the token may need to be refreshed.

Check Token flow

Request

The following parameters should be set on the request header.

• Authorization: Access-Token preceded by Bearer

Response

The response will be a standard Billing Platform API JSON response (see POST Requests).

Logout

Request

POST /v1/auth/logout
Authorization: Bearer <access-token>

Success response

HTTP/1.1 200 OK

{
  "status": "success",
  "code": 1000,
  "message": "Signed out successfully"
}

Error responses

HTTP/1.1 401 Unauthorized

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Logout from the Billing Platform API.

Logout flow

Request

The following parameters should be set on the request header.

• Authorization: Access-Token preceded by Bearer

Response

The response will be a standard Billing Platform API JSON response (see POST Requests).

APIs

Get Customer V1

Request

GET /v1/app/get_customer?token=<access_token>&page=<page_code>&some_key=some_value

Success response

HTTP/1.1 302 Found
Location: http://your-app.com?code=1000&customer=<customer ID>&message=success&network=<network code>&status=success&some_key=some_value

Error responses

HTTP/1.1 302 Found
Location: http://your-app.com?code=<error code>&status=error&message=<error description>&some_key=some_value

Gets network information and customer information (if available). To get information about the current customer, redirect the customer to the get customer endpoint.

Get Customer flow

Request

To get information about the current customer, redirect the customer to the get customer endpoint, with the following set as query parameters on the request.

• page: Page code to redirect back to
• token: Current Access-Token
• Any other query parameters sent will be appended to the redirect. This feature can be used to track the customer, track request etc.

Response

The Billing Platform API will redirect to the provided page with the following details appended as query parameters.

• customer: Customer ID (if available)
• network: Network code
• status: Response status
• code: Response code
• message: Description of the status
• plus any other query parameters sent in the request

Get Customer V2

Request

POST /v2/app/get_customer
Authorization: Bearer <access-token>

Success response

HTTP/1.1 200 OK

{
  "customer": "<customer ID>",
  "network": "<network code>",
  "status": "success",
  "message": "Success",
  "code": 1000
}

Error responses

HTTP/1.1 401 Unauthorized

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Gets network information and customer information (if available).

Get Customer flow

Request

To get information about the current customer, send a POST request to the get customer endpoint.

Response

The response will be a standard Billing Platform API JSON response with the below parameters (see POST Requests).

• customer: Customer ID
• network: Network code
• status: Response status
• code: Response code
• message: Response message

Customer Info

Request

POST /v1/app/customer_info
Authorization: Bearer <access-token>

With customer ID

{
  "customer": "<customer ID>"
}

With network code and customer MSISDN

{
  "network": "<network code>",
  "msisdn": "<msisdn>"
}

Success response

HTTP/1.1 200 OK

{
  "customer": "<customer ID>",
  "subscription_status": "<subscription status>",
  "package": "<package code>",
  "network": "<network code>",
  "status": "success",
  "code": 1000,
  "message": "Success"
}

Error responses

HTTP/1.1 401 Unauthorized

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Get the customer's subscription status.

Customer Info flow

Request

The following parameters should be set as a JSON payload on a POST request body. The customer ID or a combination of the network code and customer MSISDN may be used to fetch customer subscription information.

• customer: Customer ID

Or

• network: Network code
• msisdn: Customer MSISDN

Response

The response will be a standard Billing Platform API JSON response with the below parameters (see POST Requests).

• customer: Customer ID
• subscription_status: See subscription statuses
• package: Package code
• network: Network code
• status: Response status
• code: Response code
• message: Response message

Subscribe

Request

GET /v1/app/subscribe?token=<access_token>&package=<package_code>&customer=<customer_id>&page=<page_code>&flow=<subscription_flow>&click=<click>&publisher=<publisher>

Success redirect response

HTTP/1.1 302 Found
Location: http://your-app.com?code=1000&status=success&message=Success

Error redirect response

HTTP/1.1 302 Found
Location: http://your-app.com?code=<error code>&status=error&message=<error description>

Supported networks: Dialog, Mobitel, Hutch

To subscribe the customer via consent gateway, your app should redirect the customer to the subscription endpoint with request data set on query parameters. Thereafter, the subscription process differs between networks. Once the subscription process has completed, the Billing Platform API will initiate a callback to your app, and subsequently redirect the user to a specified page on your app after a delay of a few seconds.

See Callbacks for callback code descriptions.

Subscribe flow

Request

Redirect the customer to the endpoint, with the following parameters set as query parameters on the request.

• token: Current Access-Token
• package: Package code to subscribe the customer to
• page: Page code to redirect back to
• customer: (Optional) A customer ID
• flow: (Optional) The requested subscription flow. Values can be either consent_gateway or pin, depending on your requirement and the subscription flows allowed by the network. See the below table for supported flows. Defaults to consent_gateway.
• click: (Optional) A unique identifier for this click (e.g. pixel or click ID)
• publisher: (Optional) A publisher identifier to track this traffic with

Response

Once the subscription process has been completed by the customer, the below two responses will occur.

(1) The Billing Platform API will initiate a callback to the app callback URL specified during app setup, with the following parameters.

• code: Response code
• message: Description of the status
• customer: Customer ID
• package: Package code
• time: Timestamp of the request
• click: Click received with the subscription request (if available)
• publisher: Publisher received with the subscription request (if available)

See Callbacks for more information.

(2) The Billing Platform API will then redirect to your app's home page, with the below query parameters set, based on what action the user has taken while subscribing.

• customer: Customer ID (if available)
• subscription_status: See subscription statuses (if available)
• package: Package code (if available)
• network: Network code (if available)
• status: Response status
• code: Response code
• message: Description of the status

Unsubscribe V1

Request

POST /v1/app/unsubscribe
Authorization: Bearer <access-token>

{
  "customer": "<customer ID>"
}

Success response

HTTP/1.1 200 OK

{
  "status": "success",
  "code": 1000,
  "message": "Success"
}

Error responses

HTTP/1.1 401 Unauthorized

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Supported networks: Dialog, Hutch

Unsubscribe the given customer from your app.

Unsubscribe V1 flow

Request

The following parameters should be set as a JSON payload on the request body.

• customer: Customer ID

Response

The response will be a standard Billing Platform API JSON response (see POST Requests).

Unsubscribe V2

Request

GET /v2/app/unsubscribe?token=<access_token>&package=<package_code>&customer=<customer_id>&page=<page_code>
Authorization: Bearer <access-token>

Success redirect response

HTTP/1.1 302 Found
Location: http://your-app.com?code=1000&status=success&message=Success

Error redirect response

HTTP/1.1 302 Found
Location: http://your-app.com?code=<error code>&status=error&message=<error description>

Supported networks: Mobitel

To unsubscribe the customer, your app should redirect the customer to the unsubscription endpoint with request data set on query parameters. Thereafter, the unsubscription process differs between networks. Once the unsubscription process has completed, the Billing Platform API will initiate a callback to your app, and redirect the user to a specified page on your app.

The unsubscription success redirect page will be configured by us during app setup (usually your app's home page), and can differ from the page sent during the subscription request. The page sent with the unsubscription request will only be used if an error occurs during the subscription process.

See Callbacks for callback code descriptions.

Unsubscribe V2 flow

Request

Redirect the customer to the endpoint, with the following parameters set as query parameters on the request.

• token: Current Access-Token
• package: Package code to unsubscribe the customer from
• customer: Customer ID
• page: (Optional) Page code to redirect back to in case of an error

Response

Once the unsubscription process has been completed by the customer, the below two responses will occur.

(1) The Billing Platform API will initiate a callback to the app callback URL specified during app setup, with the following parameters.

• code: Response code
• message: Description of the status
• customer: Customer ID
• package: Package code
• time: Timestamp of the request

See Callbacks for more information.

(2) The Billing Platform API will then redirect to your app's home page.

Pin Request

Request

POST /v1/app/pin_request

{
  "msisdn": "<MSISDN>",
  "click": "<Click / pixel>",
  "publisher": "<Publisher>",
  "key": "<API key>",
  "operator": "<Operator code>",
  "package": "<Package code>"
}

Success response

HTTP/1.1 200 OK

{
  "status": "success",
  "code": 1000,
  "message": "Success",
  "reference": "<Transaction reference>"
}

Error responses

HTTP/1.1 400 Bad Request

{
  "status": "error",
  "code": "<Error code>",
  "message": "<Error description>"
}

Request a PIN code to be sent to a customer.

Request

The following parameters should be set as a JSON payload in the request body.

• msisdn: The customer MSISDN
• click: A unique click identifier
• publisher: A publisher identifier (Optional)
• key: The API key (Provided by us)
• operator: The operator code (Provided by us)
• package: The package code (Provided by us)

Response

You will receive the following parameters on the response. Also see response codes.

• status: A status
• code: A status code
• message: A status message
• reference: A unique request identifier reference

Pin Verify

Request

POST /v1/app/pin_verify

{
  "msisdn": "<MSISDN>",
  "click": "<Click / pixel>",
  "publisher": "<Publisher>",
  "key": "<API key>",
  "operator": "<Operator code>",
  "pin": "<Pin code>",
  "reference": "<Transaction reference>",
  "package": "<Package code>"
}

Success response

HTTP/1.1 200 OK

{
  "status": "success",
  "code": 1000,
  "message": "Success"
}

Error responses

HTTP/1.1 400 Bad Request

{
  "status": "error",
  "code": "<error code>",
  "message": "<error description>"
}

Verify a PIN code entered by a customer.

Request

The following parameters should be set as a JSON payload in the request body.

• msisdn: The customer MSISDN
• click: A unique click identifier
• publisher: A publisher identifier (Optional)
• key: The API key (Provided by us)
• operator: The operator code (Provided by us)
• package: The package code (Provided by us)
• pin: The PIN code entered by the customer
• reference: The reference received from the previous step - Pin Request API

Response

You will receive the following parameters on the response. Also see response codes.

• status: A status
• code: A status code
• message: A status message

Callbacks

The Billing Platform API will initiate callbacks to an app-specific endpoint for various subscription related events. You will need to provide this endpoint to us during the initial stage of integration.

Callback request

POST www.myapp.com/callback

{
  "code": "<response code>",
  "message": "<response description>",
  "customer": "<customer ID>",
  "package": "<package code>",
  "time": "<request time>",
  "click": "<click>",
  "publisher": "<publisher>"
}

Example: Customer subscribed callback

{
  "code": 4000,
  "message": "Customer subscribed",
  "customer": "06e7b363-73a4-44d5-943a-9ed3b3d30637",
  "package": "app_daily",
  "time": "2024-08-17T22:48:16.369+05:30",
  "click": "clk_00001",
  "publisher": "pub_00001"
}

Example: Customer suspended callback

{
  "code": 4002,
  "message": "Customer suspended",
  "customer": "06e7b363-73a4-44d5-943a-9ed3b3d30637",
  "package": "app_daily",
  "time": "2024-08-17T22:48:15.455+05:30"
}

Example response JSON payload to be sent back from your app

{
  "status_code": 1000,
  "status": "Successfully updated customer"
}

Callback request

The Billing Platform API will send POST request to your endpoint when subscription events occur, with a JSON payload.

Expected response

You may send any JSON response which will be used for tracking / debugging purposes only. There is no specific key / values expected, however we recommend you add status information to the response.

Callback details