CODE YOUR APPS

CAAS – API

Overview

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

  • Query Balance – This service retrieves the account balance and other related information of a given subscriber MSISDN.
  • Direct Debit – This service charges a specific amount from a subscriber’s account.
  • Get Payment Instrument List Service – This service facilitates to obtain a list of payment instruments available for a particular subscriber.
  • Charging Notification – This service facilitates SDP in sending the payment’s status to the application, which sends a charging request.

HTTP Rest

In this context, both requests/responses used to exchange information are with content type “application/json”.

JSON Objects

JSON objects are used as content type to communicate between application and TAP. JSON is an open, text-based data exchange format; it is human-readable, platform independent, and supports a wide availability of implementations.

CAAS

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

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 Post paid) and Account’s status (Activate or Disable).

The URL for Query Balance service is as follows:

http://[ ip ]:port /caas/ balance/query

Note: [ ip ] field should be the URL of the IdeaPro live server. Service Providers who tests third party applications via SDK shall use 127.0.0.1 as the [ ip ].

Request

Following is a sample request for query balance service.

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:

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/Post paid 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 per request.

String Mandatory
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
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:

Direct Debit

This service charges a specific amount from a subscriber’s account.

The URL for Direct Debit service is as follows:

http:// [ip]:port /caas/direct/debit

Note: [ ip ] field should be the URL of the IdeaPro live server.
Service Providers who tests third party applications via SDK shall use 127.0.0.1 as the [ ip ].

Request

Following is a sample request for direct debit service.

Following are the request parameters of deliver 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 nquires 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

Subcriber: tel:94232323232

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

Comprehensive sample request:

Response

Following are the response parameters of deliver 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 failed transaction.

Only a single value can be sent per request.

Date/Time string in ISO-8601 format

e.g.’2011-08- 23T16:50:31.418 +05:30′

Mandatory
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

Comprehensive sample response:

Status Codes and Error Codes

Status Codes (Non Retry able)

Code Description
S1000 Process completed successfully for all the available destination numbers

Error Codes (Non Retry able)

Code Description
E1313 Authentication failed. No such active application with applicationId “application-id”, or no active service provider or the given password in the request is invalid.
E1303 IP address from which this request originated is not provisioned to send request to application “application-id”. Please use a provisioned system to send request or contact system admin to provision the new IP.
E1317 “MSISDN” in request is invalid or not allowed.
E1328 Charging operation {operation} not allowed. Please check the NCS configuration.
E1337 Duplicate request.
E1601 System experienced an unexpected error.
E1343 MSISDN is not white listed. Only white list numbers are allowed to send messages at this state.
E1318 Transaction limit per second has exceeded. Please throttle requests not to exceed the transaction limit. Contact TAP admin to increase the traffic limit.
E1319 Transaction limit for today is exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit
E1326 Insufficient balance.
E1602 Message delivery failed. Please retry
E1603 Temporary System Error occurred while delivering your request.

Error Codes (Retry able)

Code Description
E1318 Transaction limit per second has exceeded. Please throttle requests not to exceed the transaction limit. Contact TAP admin to increase the traffic limit.
E1319 Transaction limit for today is exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit
E1326 Insufficient balance.
E1602 Message delivery failed. Please retry
E1326 Temporary System Error occurred while delivering your request.

What follows is a list of definitions of all terms, acronyms and abbreviations required to properly interpret this document.

  • NCS – Network Capability Service
  • SMS – Simple Message Service
  • HTTP – Hyper Text Transfer Protocol
  • MO – Mobile Originated
  • MT – Mobile Terminated
  • MSISDN – Mobile Station Integrated Services Digital Network
  • SLA – Service Level Agreement