CaaS API


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": "94771234567"
}

 

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": "94771234567",
  "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": "94771234567",
  "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.

String Mandatory 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:94773687964", 
     "amount":"10.00", 
     "currency":"LKR",  
     "applicationId":"APP_003483", 
     "password":"10d78f7aba804398e5a6157028f52264", 
     "subscriberId":"tell:94773687964", 
     "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

 

Request

Following are the request parameters of Get Payment Instrument List service.

Parameter Name Description Type Mandatory/Optional
applicationId appId of the app String Mandatory
password Password of the app String Mandatory
subscriberId This can be the MSISDN or the Username of the subscriber. This is a unique identifier.
Tel: is for MSISDN,
tel: 94771234567
Note: tel might be a masked number depending on the type of the application
String Mandatory
type Payment instrument typePossible values:- sync- async

– all (by default: all)

Enum
sync
async
all
Optional

 

Comprehensive sample request for Get Payment Instrument List service is as follows.


{ 
     "applicationId":"APP_003360",                
     "password":"ed3e96aca9ad2be1d22731bb0e8420c3",    
     "subscriberId":"tel:94772345678", 
     "type":"all" 
}

 

 

Response

Following are the response parameters of Get Payment Instrument List service.

 

Parameter Name Description Type Mandatory/Optional
paymentInstrumentList This is the list of payment instruments configured to the subscriber.It should be as follows.Eg:
[
{"name":"Mobile account", "type":"sync"},
{"name":""Dialog-Ezcash"","type":"async"}
]

Only a single set of elements per request

String Mandatory
statusCode Status of the operation String Mandatory
statusDetail The textual description of the operation’s status String Mandatory

 

Comprehensive sample response for Get Payment List service is as follows.

{ 
      "statusCode":"S1000", 
      "statusDetail":"Success",                          
      "paymentInstrumentList":[{"type":"ASYNC","name":"Dialog-Ezcash"}] 
}

 

 

Charging Notification

This service is provided through the CAAS API and facilitates SDP in sending the payment’s status to the application, which sends a charging request.

After the subscriber sends a charging request, the application will receive a charging notification. If there are partial and (or) over payments done to a particular referenceId, then the notification sent to the application will contain a cumulative total for the particular referenceId.

 

NOTE: The charging notification is received to the URL which is configured when provisioning.

 

Request

Following is a sample request for charging notification service.

Parameter Name Description Type Mandatory/Optional
externalTrxId This is 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.Only a single value can be sent per request. String Mandatory
referenceId

Transaction ID sent from EZ Cash.Only a single value can be sent per request. 8 digits

Mandatory if response is received from EZ Cash

paidAmount Exact amount paid by subscriber String Mandatory
currency The currency of the amount String Mandatory
totalAmount

Accumulated partial or overpayments made by subscriber for the same referenceId.This must be specified if partial and (or) over payments are allowed String Mandatory
balanceDue

The balance that must be paid by the subscriber.This must be specified if over payments are not allowed and partial payments allowed String Mandatory
statusCode Status of the operation String Mandatory
statusDetail The textual description of the operation’s status. String Mandatory
timestamp Date and time of the payment according to external PI system. Mandatory

 

Comprehensive sample request for success scenario is as follows.

{ 
      paidAmount='25.00', 
      externalTrxId='456123', 
      internalTrxId='913100816320004', 
      referenceId='17839448', 
      totalAmount='25', 
      balanceDue='0.00', 
      currency='LKR', 
      statusCode='S1000', 
      statusDetail='Request was Successfully processed, Due amount fully paid.', 
      timeStamp='08-Oct-2013 16:32' 
}

 

 

Comprehensive sample request for failed scenario is as follows.

{ 
      paidAmount='25.00', 
      externalTrxId='456123', 
      internalTrxId='913100816290003', 
      referenceId='17839448', 
      totalAmount='0',
      balanceDue='25.00',
      currency='LKR', 
      statusCode='E1404',
      statusDetail='Charging request failed',       
      timeStamp='08-Oct-2013 16:32' 
}

 

 

Response

Following is a sample response for charging notification service.

Parameter Name Description Type Mandatory/Optional
statusCode Status code indicating if the notification was received. String Mandatory
statusDetail The textual description of the status. String Mandatory

 

Comprehensive sample response is as follows.

{ 
      "statusCode":"S1000", 
      "statusDetail":"Success",                  
}

 

 

 

Using the Simulator

 

CAAS Request

Caas (Charging as a Service) enables applications to charge and to get account information from subscribers.

This simulator can set an initial balance for the account. Balance can be queried (in Query Balance) and also can be used in debit transactions (Direct Debit).

 

Query Balance

Application can send the “Query Balance” request to the simulator to retrieve the current balance of the particular subscriber’s account.

The application has to send the query balance request to following url

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

Figure 1.1

Figure 1.1

 

 

 

 

 

 

 

 

 

To set the balance, user needs to enter the required amount in the relevant text field and click on “Set Balance”. The amount will be set as the account balance.

Figure 1.2

Figure 1.2

 

In addition, the values set for Account type, Account Status are used in the Query Balance response.

Figure 1.3

Figure 1.3

 

To simulate error scenarios, the user has to select the appropriate status code from the “Status Code” list.

 

Field name Description Sample value
Set Balance Sets the initial balance for the account.
Account Type Select the account type
Account Status Specify the account status Pre-paid, Post paid
Status Code Set the Status Code Active, Blocked

 

Refer following for the sample request and response.

Figure 1.4

Figure 1.4

 

When Query Balance Request is sent, the response will send the current account balance along with other account related details. (Refer the figure above.)

 

In case of an error scenario, refer the following screens for the request and response.

Figure 1.5

Figure 1.5

 

Figure 1.6

Figure 1.6

 

 

Direct Debit

The application has to send the direct debit request to following url.

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

 

Figure below shows a direct debit transaction of 100 units for an account with a balance of 1000 units.

Figure 1.7

Figure 1.7

 

Following is the response.

Figure 1.8

Figure 1.8

 

The transaction has been done successfully as the account had sufficient balance.

Following screen shows few more successful transactions.

Figure 1.9

Figure 1.9

 

Now the account has zero balance. In such scenario, if a transaction is attempted, it will be failed.

Following screen shows a sample of an error scenario with insufficient balance.

Figure 2.0

Figure 2.0

 

In case of an error scenario, refer the following screens for the request and response.

Figure 2.1

Figure 2.1

 

Figure 2.2

Figure 2.2