Credit Balance

For accounts with pre-paid payment plan, the balance on client account is updated on requests that involve using credit. Such requests include sending SMS or Voice messages. If the available credit in client is not enough to proceed, the request will be ignored.

Applications can request for current credit balance on account through API calls. This section gives insight on how to make request for account credit balance.

Balance Request

Making a request for account credit balance does not require much information. The only information required is the API key for accessing the API endpoint for account credit balance.

The API endpoint for making request for account credit balance is given as follows:

https://api.smsonlinegh.com/v5/account/balance

As has been done in all requests discussed so far, the account API key has to be specified in the request headers. The value for the account API key must be set as key API_KEY. For example:

key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128.

This must be set for the Authorization header.

Additionally, client must specify the content type of the response that they want to receive in the Accept header. That is, whether client wants the response to be returned as application/json or application/xml

POST https://api.smsonlinegh.com/v5/account/balance

Host: smsonlinegh.comAccept: application/json
Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128

The following is a sample code that makes a request for account credit balance. Observe that no data is set for the request body. The only client information required is the account API key which is set as the value for the Authorization header.

<?php
// API endpoint for the request.
// If [https] is not supported when testing,
// then change the request protocol to [http]
$endPoint = 'https://api.smsonlinegh.com/v5/account/balance';

// set up the request headers
$headers = [
    'Host: api.smsonlinegh.com',
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
];

$ch = curl_init($endPoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute for response
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// close curl
curl_close($ch);

if ($httpCode == 200){
    var_dump($response);
}

# API host domain
host = 'api.smsonlinegh.com'

# API request URL
requestURL = 'http://api.smsonlinegh.com/v5/account/balance'

# set up the request headers
headers = dict()
headers['Host'] = host
headers['Content-Type'] = 'application/json'
headers['Accept'] = 'application/json'
headers['Authorization'] = 'key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'

httpConn = httpClient.HTTPConnection(host)
httpConn.request('POST', endPoint, None, headers)

# get the reponse
response = httpConn.getresponse()

if response.status == 200:
    print(response.read())
else:
    print('Request was unsuccessful')

const axios = require('axios');

let endPoint = `http://api.smsonlinegh.com/v5/account/balance`;

// set up the request headers
let headers = {
    'Host': 'api.smsonlinegh.com',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
};

// request for account balance
axios.request({
    url: endPoint,
    method: 'post',
    headers: headers
})
.then(function(response){
    // the http status code
    let httpStatus = response.status;
		
    if (httpStatus == 200){
        let responseData = response.data;
        console.log(responseData);
    }
})
.catch(function(error){
    console.log(error);
});

When the request is submitted with valid information, a credit balance response will be returned. This is considered next.

Balance Response

A request for account credit balance returns balance response data for the account. A sample balance response data based on an account with quantity credit model is shown below:

JSON
XML

{
    "handshake" : {
        "id": 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "balance": 2432,
        "model": "quantity",
        "currencyName": null,
        "currencyCode": null
    }
}

<response>
    <handshake>
        <id>0</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <balance>2432</balance>
        <model>quantity</model>
        <currencyName>null</currencyName>
        <currencyCode>null</currencyCode>
    </data>
</response>

As can be seen, the data section of the response contains the account credit balance set to the balance property. The balance can be in quantity or currency value. This depends on the credit model set on the client account. The balance response shown above is based on an account with quantity credit model.

Quantity Credit Model

A quantity credit model set on an account implies that the client credit is based on quantifiable units. This typically applies to accounts with only SMS service. For example, the quantity of SMS credit remaining.

In this case, the credit model set in the response is quantity, as can be seen set to the model property of the response data.

With quantity credit model, the currencyName and currencyCode of the response will all have the value null since the balance is not based on any currency information.

The previous sample response is an example of a response with quantity credit model.

Currency Credit Model

If an account has a currency credit model, then the model property of the balance response will have the value currency. This implies that the client account balance is valued in currency amount. In this case, the currencyName and currencyCode will be set to the billing currency information as set in client account.

The following shows a balance response based on account with currency credit model.

JSON
XML

{
    "handshake" : {
        "id": 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "balance": 350,
        "model": "quantity",
        "currencyName": "Ghana Cedi",
        "currencyCode": "GHS"
    }
}

<response>
    <handshake>
        <id>0</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <balance>350</balance>
        <model>quantity</model>
        <currencyName>Ghana Cedi</currencyName>
        <currencyCode>GHS</currencyCode>
    </data>
</response>

The currency credit model typically applies to accounts with multiple services. However, it is possible for an account with only SMS service to also have a currency credit model.