Skip to content

Charging API

CaaS - Charging as a Service API allows the service provider to perform query balance and charge a specific amount from the end user.

P.S - It is a must to use a pre-defined specific amount to charge from the end user, which should also be communicated to the end user prior to the registration.

In this documentation, following services offered by the API are found.

  • Query Balance
  • Direct debit

Query Balance

This service provides the remaining balance amount of a desired user with other related information of the user account.

This service is still not availabe under Ideamart by Smart for Smart Axiata service providers

URL

https://api.ideamart.io/caas/balance/query

Content Type

application/json

Method

POST

Request

Sample request of balance query is below.

{
    "applicationId":"APP_000018", 
    "password":"95904999aa8edb0c038b3295fdd271de", 
    "subscriberId":"************"
}

Response

Sample response of balance query is below.

{
    "chargeableBalance":"300.0", 
    "statusCode":"S1000", 
    "statusDetail":"Success", 
    "accountStatus":"Active", 
    "accountType":"Pre Paid"
}

More information on Balance Query service

Following are all the request parameters of the balance query service.

Parameter Type Description Type Mandatory/Optional
applicationId Used to identify the application. This is a unique identifier generated while provisioning an application. String Mandatory
password Used to authenticate the application originated message against the service providers credentials.
Encoded, single value
String Mandatory
subscriberId This can be the MSISDN or the Username of the subscriber whose account balance is being queried String Mandatory
accountId The account of the payment instrument. Only a single value can be sent per request String Optional
currency The currency of the charged amount. Only a single value is allowed, and must be in 'LKR' since service is only available for Dialog, Airtel and Hutch. String Optional

Below is a comprehensive sample of the balance query request.

{
    "applicationId":"APP_000018", 
    "password":"95904999aa8edb0c038b3295fdd271de", 
    "subscriberId":"94776351232",                       
    "accountId":"12345",
    "currency":"LKR"
}

Following are all the response parameters of balance query service.

Parameter Description Type M/O
accountType Account type of the subscriber id. (Prepaid/Postpaid for GSM domain) String M
accountStatus Account status of the subscriber ID String M
statusCode Status of the operation.
Only a single set of elements can be sent per request.
String M
statusDetail The textual description of the operation's status. String M
chargeableBalance Available chargeable balance of the subscriber.
Refers to either remaining account balance (prepaid user) or the difference between credit limit and outstanding bill (postpaid user).
String M

Below is a comprehensive sample for the balance query response.

{
 "chargeableBalance":"300.0", 
 "statusCode":"S1000", 
 "statusDetail":"Success", 
 "accountStatus":"Active", 
 "accountType":"Pre Paid"  
}

Direct Debit

This is used to charge a specific amount from the subscriber's account for the service provided. This amount has to be communicated to the user prior to subscription.

URL

https://api.ideamart.io/caas/direct/debit

Content Type

application/json

Method

POST

Request

Following is a sample request for direct debit service.

{   
    "applicationId":"APP_000017", 
    "password":"95904999aa8edb0c038b3295fdd271de",
    "externalTrxId":"12345678901234567890123456789012",
    "subscriberId":"tel:************",
    "accountId":"123456",
    "currency":"USD",
    "amount":"1"
}

Response

Following is a sample response for direct debit service.

{
    "statusCode":"S1000", 
    "timeStamp":"2012-07-30T12:48:10-0400",
    "shortDescription":"Long Description",
    "statusDetail":"Success",
    "externalTrxId":"12345678901234567890123456789012",
    "longDescription":"short Description",
    "internalTrxId":"321"   
}

More information on Direct Debit

Following are all the request parameters of the direct debit service.

Parameter Description Type M/O
applicationId Used to identify the application. This is a unique identifier generated when provisioning an application. String M
password Used to authenticate the application originated message against the service providers credentials. String M
externalTrxId This is the transaction ID generated by the application to map the request with the response. String M
subscriberId This is the MSISDN of the subscriber to be charged. This is a unique identifier. The hash key of the charged user String M
accountId The account of the payment instrument. String O
amount Amount to be reserved for charging. String M
currency The currency of the amount. Optional, but if not 'LKR', must be specified which currency it is. String O
paymentInstrument The account which the debit should be performed on. String M

Below is a comprehensive sample for the direct debit request.

{
    "applicationId":"APP_000017",
    "password":"95904999aa8edb0c038b3295fdd271de",
    "externalTrxId":"12345678901234567890123456789012",
    "subscriberId":"94776351232",
    "accountId":"123456",
    "paymentInstrument":"MobileAccount"
    "currency":"USD",
    "amount":"1"
}

Following are all the response parameters of the direct debit service.

Parameter Description Type M/O
externalTrxId The transaction ID generated by the application to map the request with the response. String M
internalTrxId Internal Transaction ID generated by the Payment Gateway for the transaction. This is unique for a transaction String M
referenceId Unique number generated by the system for the payment request. This is required to be entered in the external charging system/menu. 8 digits O
timeStamp System date and time of success or failed transaction. Date/Time string (ISO-8601)
statusCode Status of the operation. String M
statusDetail The textual description of the operation status String M

Below is a comprehensive sample for the direct debit response.

{
    "statusCode":"S1000", 
    "timeStamp":"2012-07-30T12:48:10-0400", 
    "shortDescription":"short Description", 
    "statusDetail":"Success", 
    "externalTrxId":"12345678901234567890123456789012", 
    "longDescription":"Long Description", 
    "internalTrxId":"321"
}