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