CaaS API

Let’s say that you created an applications and need to monetize your application so that your hard work pays off. Caas (Charging as a Service) is the API you will need to use. This monetizes your app with micro-payments. You can retrieve the account balance and other related information of a given subscriber, charge specific amount from a subscriber’s account etc

 

Applications have CaaS NCS access if charging as a service requests are required by the application.

Method

POST

Query Balance

This service retrieves the account balance and other related information of a given subscriber MSISDN. Account information comprises of Account type (Pre-paid or Postpaid) and Account’s status (Activate or Disable). URL,to send Query balance request is as follows:

Simulator:

http://localhost:7000/caas/get/balance

Active production:

https://api.dialog.lk/caas/balance/query

Request

Following is a sample request for query balance service.
 {  “applicationId”:
“APP_000018”,
“password”: “95904999aa8edb0c038b3295fdd271de”,
“subscriberId”: “5C74B588F97”}
Following are the Request parameters of send service.
Parameter Name Description Type Mandatory/ Optional
applicationId
Used to identify the application. This is a unique identifier generated while provisioning an application.Only a single value can be sent per request.
String (32)
Mandatory
password
Used to authenticate the application originated message against the service providers credentials.Encoded, single value.
String (32)
Mandatory
subscriberId
This can be the MSISDN or the Username of the subscriber whose account balance is being queried.
Note: tel might be a masked number depending on the type of the application.
Only a single value can be sent per request.
String
Mandatory
paymentInstrumentName
The name of the payment instrument.Only a single value can be sent per request.
Enumerator
Mandatory
accountId
The account of the payment instrument.Only a single value can be sent per request.
String
Optional
currency
The currency of the amount.Only a single value can be sent per request.Only ‘LKR’ is allowed.
String
Optional
Comprehensive sample request:
 {  “applicationId”: “APP_000018”,
“password”: “95904999aa8edb0c038b3295fdd271de”,
“subscriberId”: “5C74B588F97”,
“paymentInstrumentName”: “MobileAccount”,
“accountId”: “12345”,
“currency”: “LKR”}

 

Response

Following are the response parameters of query balance service
Parameter Name Description Type Mandatory/ Optional
accountType
Account type of the subscriber id.E.g. Prepaid/Postpaid for GSM domain.Only a single set of elements can be sent per request.
String
Mandatory
accountStatus
Account status of the subscriber ID. Only a single set of elements can be sent perrequest
String
Mandatory
statusCode
Status of the operation.Only a single set of elements can be sent perrequest.
String
Mandatory
statusDetail
The textual description of the operation’s status.Only a single set of elements can be sent per request.
String
Mandatory
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). Only a single value can be sent per request.
String(rounded up to two decimal points)
Mandatory

 

Comprehensive sample response:
 {  “chargeableBalance”: “300.0”,
“statusCode”: “S1000”,
“statusDetail”: “Success”,
“accountStatus”: “Active”,
“accountType”: “Pre Paid”}

 

Direct Debit

This service charges a specific amount from a subscriber’s account. URL, to send the Direct Debit request is as follows:

Simulator:

http://localhost:7000/caas/direct/debit

Active production:

https://api.dialog.lk/caas/direct/debit

 

Request

Following is a sample request for direct debit service.
 {  “applicationId”: “APP_000017”,
“password”: “95904999aa8edb0c038b3295fdd271de”,
“externalTrxId”: “12345678901234567890123456789012”,
“subscriberId”: “5C74B588F97”,
“amount”: “100”}

 

 

Following are the request parameters of direct debit service.
Parameter Name Description Type Mandatory/ Optional
applicationId
Used to identify the application. This is a unique identifier generated by the SDP when provisioning an application.Only a single value can be sent per request.
String(32)
Mandatory
password
Used to authenticate the application originated message against the service providers credentials.Encoded, single value
String(32)
Mandatory
externalTrxId
This is the transaction ID generated by the application to map the request with the response.This is needed to avoid any conflicts when SP inquires about a transaction.Only a single value can be sent per request.
String(32)
Mandatory
subscriberId
This can be the MSISDN the subscriber to be charged. This is a unique identifier.
Tel: is for MSISDN tel:947758456325
Note: tel might be a masked number depending on the type of the application.
Only a single value can be sent per request.
String
Mandatory
paymentInstrumentName
The name of the payment instrument.Only a single value can be sent per request.
Enumerator
Mandatory
accountId
The account of the payment instrument.Only a single value can be sent per request.
String
Optional
amount
Amount to be reserved for charging.Only a single value can be sent per request.
String(rounded up to two decimal points)
Mandatory
currency
The currency of the amount.Only a single value can be sent per request.Only ‘LKR’ is allowed.
String
Optional
additionalParams
A Json object with key value pairs for additional parameters.Eg:
{“ezcashAgentPin”:”4444?,”ezcashAgentAlias”:”VC_0000?}This is used to manage additional parameters specific for eZ cash payment instruments.
     ezcashAgentPin – ez Cash Agent PIN which is sent by SP.
     ezcashAgentAlias – Merchant PIN which is used to uniquely identify the merchant.StringMandatory only if payment instrument is eZ Cash

 

Comprehensive sample request:
 {  “applicationId”: “APP_000017”,
“password”: “95904999aa8edb0c038b3295fdd271de”,
“externalTrxId”: “12345678901234567890123456789012”,
“subscriberId”: “94771234567”,
“paymentInstrumentName”: “MobileAccount”,
“accountId”: “123456”,
“currency”: “LKR”,
“amount”: “100”}

 

Comprehensive sample request for eZ cash integration:
{     “externalTrxId”:”456123″,
“paymentInstrumentName”:”Dialog-Ezcash”,
“accountId”:”tel: 5C74B588F97″,
“amount”:”10.00″,
“currency”:”LKR”,
“applicationId”:”APP_003483″,
“password”:”10d78f7aba804398e5a6157028f52264″,
“subscriberId”:”tell: 5C74B588F97″,
“additionalParams”:
{            “ezcashAgentPin”:”4444″,
“ezcashAgentAlias”:”VC_0000″
}
}

 

NOTE: In eZ cash integration,

The value for ‘paymentInstrumentName’ should hold “Dialog-Ezcash”.

Extra parameters; ‘ezcashAgentPin’ and ‘ezcashAgentAlias’ are added to eZ cash request to pass merchant Id and eZ cash PIN through NBL.

Response

Following are the response parameters of direct debit service.
Parameter Name Description Type Mandatory/ Optional
externalTrxId
The transaction ID generated by the application to map the request with the response.Only a single value can be sent per request.
String
Mandatory
internalTrxId
Internal Transaction ID generated by the Payment Gateway for the transaction. This is unique per transaction.Only a single value can be sent per request.
String(32)
Mandatory
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
Optional
timeStamp
System date and time of success or failedtransaction.Only a single value can be sent per request.
Date/Time string in ISO-8601format.
e.g.’2011-08-23T16:50:31.418+05:30?
statusCode
Status of the operation.Only a single set of elements can be sent per request.
String
Mandatory
statusDetail
The textual description of the operation’s status.Only a single set of elements can be sent per request.
String
Mandatory
shortDescription
Short description. This can be used to send payment instructions to the application user.
String
Mandatory for the ezcash integration
longDescription
Long description used in case of asynchronous transactions only. (Future parameter required for m-commerce applications.)
String
Mandatory

 

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

 

Comprehensive sample response for eZ cash integration:
{       “statusCode”:”P1003″,
“timeStamp”:”2014-02-11T14:19:44.656+05:30″,
“shortDescription”:”\”Please dial #111# and authorize the transaction to complete the payment; Amount:Rs 8\””,
“externalTrxId”:”456123″,
“statusDetail”:”Request successful. Payment notification pending from payment instrument”,
“longDescription”:”Please dial #111# and authorize the transaction to complete the payment; Amount:Rs 8″,
“amountDue”:”8″,        “internalTrxId”:”914021114190001″ }

 

NOTE: In eZcash response, the ‘longDescription’, which is an unused parameter of the currently available Direct Debit CaaS API, will be set by SDP when responding to the application.

 

Get Payment Instrument List Service

This service is provided by Ideamart to facilitate obtaining the list of payment instruments available for a particular subscriber. The URL for Get Payment Instrument List service is as follows:

 

Simulator:

http://localhost:7000/caas/list/pi

Active Production:

https://api.dialog.lk/caas/list/pi