Supported Request Type

6 Supported Request Type

RESTClient supports three types of requests:

BalanceTransfer
ApplyLoan
GenericRequest

Note:

If the location fetch fails during BalanceTransfer or ApplyLoan APIs, Convergent Charging Controller does not send any location attributes to BRM. In such cases, taxes are applied based on how it is configured in the BRM system.

BalanceTransfer

BalanceTransfer request is triggered when the following parameter is present in the input xml request:

<operation>BalanceTransfer</operation>

Note:

Configure BalanceTransfer under restendpoint in config.json file.
The output request will be always POST.

Input Request

Table 6-1 describes the parameters accepted in the XML <requestDetails> tag.

Table 6-1 Input Request Parameters

Notification Type	Mandatory/Optional	Description
sourceMSISDN	Mandatory	Source MSISDN for BalanceTransfer.
destinationMSISDN	Mandatory	Destination MSISDN for BalanceTransfer.
transferAmount	Mandatory	Amount to be transferred from source to destination.
transferAmountType	Optional	ResourceId of the amount passed. If not present in the input request, default value of resourceid from the config file is used.
chargeSource	Optional	Boolean flag to indicate whether the source account will be charged. If not present in the input request, default value of chargesource from the config file is used.
chargeDestination	Optional	Boolean flag to indicate whether the target or destination account will be charged. If not present in the input request, default value of chargedestination from the config file is used.
sourceZoneMapTarget	Optional	Cellid for source MSISDN. If not present in the input request, location will not be sent to the REST server.
targetZoneMapTarget	Optional	Cellid for destination MSISDN. If not present in the input request, location will not be sent to the REST server.

Sample XML Input Request

Following is a sample XML input request sent out from DAP module.

<operation>BalanceTransfer</operation>
<requestDetails>
<sourceMSISDN>90989098</sourceMSISDN>
<destinationMSISDN>89878987</destinationMSISDN>
<transferAmount>10</transferAmount>
<transferAmountType>840</transferAmountType>
<chargeSource>true</chargeSource>
<chargeDestination>false</chargeDestination>
<sourceZoneMapTarget>52021005DC03EA</sourceZoneMapTarget>
<targetZoneMapTarget>52121005DC03EA</targetZoneMapTarget>
</requestDetails>

REST Request Parameters

Table 6-2 lists the parameters sent to the REST server.

Table 6-2 REST Request Parameters

Notification Type	Mapping From Input Request
sourceRef.id	From sourceMSISDN.
sourceRef.type	Always set as service.
targetRef.id	From destinationMSISDN.
targetRef.type	Always set as service.
transferAmount	From transferAmount.
transferAmountType	From transferAmountType. If not present in the input request, restendpoint.BalanceTransfer.resourceid from the config file is used.
chargeSource	From chargeSource. If not present in the input request, restendpoint.BalanceTransfer.chargesource from the config file is used.
chargeDestination	From chargeDestination. If not present in the input request, restendpoint.BalanceTransfer.chargedestination from the config file is used.
description	Same as operation name.
sourceLocation. zoneMapTarget	From sourceZoneMapTarget.
targetLocation. zoneMapTarget	From targetZoneMapTarget.

Sample REST API Request

Following is a sample REST API request sent out from RESTClient towards REST endpoint.

{    
  "description" : "BalanceTransfer",
  "sourceRef" : {
    "id" : "90989098",
    "type" : "service"
  },
  "targetRef" : {
    "id" : "89878987",
    "type" : "service"
  },
  "transferAmount" : 10,
  "transferAmountType" : 840,
  "chargeSource" : true,
  "chargeDestination" : false,
  "sourceLocation" : {
    "zoneMapTarget" : "52021005DC03EA"
  },
  "targetLocation" : {
    "zoneMapTarget" : "52121005DC03EA"
  }
}

REST API Response

Tags present in the response will not be validated. JSON message will be directly converted to XML.

Sample REST API Response

Following is the snippet of response received from the REST endpoint.

{
    "extension": null,
    "id": "0.0.0.1+-event-audit-transfer_balance+335711686285720131",
    "uri": "http://hostname:port/bcws/webresources/v1.0/billunits/balancegroups/transferbalance/0.0.0.1+-event-audit-transfer_balance+335711686285720131",
    "transferAmount": 10,
    "transferAmountType": 840,
    "sourceRef": {
        "id": "90989098",
        "type": "service"
    },
    "targetRef": {
        "id": "89878987",
        "type": "service"
    },
    "sourceBucket": [
        {
            "validFrom": 1647993600000,
            "validTo": 0,
            "currentBalance": 2147485311.57
        }
    ],
    "targetBucket": [
        {
            "validFrom": 1647993600000,
            "validTo": 0,
            "currentBalance": -2147483808.93
        },
        {
            "validFrom": 1632230093000,
            "validTo": 1703164493000,
            "currentBalance": 0
        }
    ],
    "sourceTransferFee": {
        "amount": 3.00,
        "feeTax": 0.30,
        "resourceId": 840
    },
    "targetTransferFee": {
        "amount": 3.00,
        "feeTax": 0.60,
        "resourceId": 840
    }
}

where, hostname and port is the hostname and port of the machine where REST server is running.

XML Response

XML response will have extra tag <rest_result_code> containing the status code from REST response header. The status code from RESTClient to DAP will always be 200. <rest_status_code> can be used for checking the status code from REST server.

Sample XML Response

Following is the XML response received by DAP for a particular request.

<targetRef>
    <id>89878987</id>
    <type>service</type>
</targetRef>
<extension>null</extension>
<targetBucket>
    <currentBalance>-2.14748380893E9</currentBalance>
    <validFrom>1647993600000</validFrom>
    <validTo>0</validTo>
</targetBucket>
<targetBucket>
    <currentBalance>0</currentBalance>
    <validFrom>1632230093000</validFrom>
    <validTo>1703164493000</validTo>
</targetBucket>
<targetTransferFee>
    <amount>3.0</amount>
    <resourceId>840</resourceId>
    <feeTax>0.6</feeTax>
</targetTransferFee>
<transferAmount>10</transferAmount>
<sourceTransferFee>
    <amount>3.0</amount>
    <resourceId>840</resourceId>
    <feeTax>0.3</feeTax>
</sourceTransferFee>
<transferAmountType>840</transferAmountType>
<id>0.0.0.1+-event-audit-transfer_balance+335711686285720131</id>
<sourceRef>
    <id>90989098</id>
    <type>service</type>
</sourceRef>
<sourceBucket>
    <currentBalance>2.14748531157E9</currentBalance>
    <validFrom>1647993600000</validFrom>
    <validTo>0</validTo>
</sourceBucket>
<uri>http://hostname:port/bcws/webresources/v1.0/billunits/balancegroups/transferbalance/0.0.0.1+-event-audit-transfer_balance+335711686285720131</uri>
<rest_status_code>201</rest_status_code>

ApplyLoan

ApplyLoan request is triggered when the following parameter is present in the input request.

<operation>ApplyLoan</operation>

Note:

Configure ApplyLoan under restendpoint in config.json file.
The output request will be always POST.

Input Request

Table 6-3 describes the parameters accepted in the XML <requestDetails> tag.

Table 6-3 Input Request Parameters

Notification Type	Mandatory	Description
sourceMSISDN	Mandatory	Source MSISDN for ApplyLoan.
loanAmount	Mandatory	Amount for loan.
loanResourceId	Optional	ResourceId of the amount passed. If not present in the input request, default value of resourceid from the config file is used.
sourceZoneMapTarget	Optional	Cellid for source MSISDN. If not present in the input request, location will not be sent to the REST server.

Sample XML Input Request

Following is a sample XML input request sent out from DAP module.

<operation>ApplyLoan</operation>
<requestDetails>
<sourceMSISDN>635495522</sourceMSISDN>
<loanAmount>5</loanAmount>
<loanResourceId>840</loanResourceId>
<serviceType>/service</serviceType>
<sourceZoneMapTarget>52021005DC03EA</sourceZoneMapTarget>
</requestDetails>

REST Request Parameters

Table 6-4 lists the parameters sent to the REST server.

Table 6-4 REST Request Parameters

Notification Type	Mapping From Input Request
accountRef.id	Always set as "0.0.0.1+-account+1".
service.id	From sourceMSISDN.
service.type	From serviceType. If not present in the input request, restendpoint.ApplyLoan. serviceType from the config file is used.
amount	From loanAmount.
resourceId	From loanResourceId. If not present in the input request, restendpoint.ApplyLoan.resourceid from the config file is used.
zoneMapTarget	From userLocation. If not present in the input request, this parameter will not be sent.

Sample REST API Request

Following is a sample REST API request sent out from RESTClient towards REST endpoint.

{
    "accountRef": {
        "id": "0.0.0.1+-account+1"
    },
  "service": {
        "id" : "635495522",
        "type" : "/service"
    },
    "amount": 5,
    "resourceId": 840,
    "zoneMapTarget": "52021005DC03EA"
}

REST API Response

Tags present in the response will not be validated. JSON message will be directly converted to XML.

Sample REST API Response

Following is the snippet of response received from the REST endpoint.

{
    "extension": null,
    "availableLoanBalance": 172,
    "currentBalance": 800,
    "amount": 122,
    "loanFee": 10,
    "tax": 8.54,
    "balances": [],
    "availableLoanLimit": 9510.91,
    "creditLimit": 10000,
    "loanObj": {
        "id": "0.0.0.1+-event-billing-loan_debit+335782055029906029",
        "uri": null
    },
    "loanFeeObj": {
        "id": "0.0.0.1+-event-billing-loan_fee+335782055029904493",
        "uri": null
    }
}

XML Response

XML response will have extra tag <rest_result_code> containing the status code from REST response header. The status code from RESTClient to DAP will always will be 200. <rest_status_code> can be used for checking the status code from REST server.

Sample XML Response

Following is the XML response received by DAP for a particular request.

<extension>null</extension>
<amount>122</amount>
<loanFee>10</loanFee>
<loanObj>
    <id>0.0.0.1+-event-billing-loan_debit+335782055029906029</id>
    <uri>null</uri>
</loanObj>
<currentBalance>800</currentBalance>
<creditLimit>10000</creditLimit>
<loanFeeObj>
    <id>0.0.0.1+-event-billing-loan_fee+335782055029904493</id>
    <uri>null</uri>
</loanFeeObj>
<tax>8.54</tax>
<availableLoanLimit>9510.91</availableLoanLimit>
<availableLoanBalance>172</availableLoanBalance>
<rest_status_code>201</rest_status_code>

GenericRequest

For sending any request (other than BalanceTransfer and ApplyLoan) to a third party REST endpoint, generic request option can be used. You can configure the required operation with the corresponding endpoint in the config.json file and then use the same operation name in the input xml triggered from DAP to REST client.

Configure the new operation in the config.json file as follows:

"restendpoint": {
   "OperationName" : {
      "endpoint" : "restendpoint",
      "type" : "POST",
      "servergroupid" : "BRM"
    }
 }

Note:

Generic request Handler supports POST, PUT, and GET requests.
servergroupid and endpoint can be custom configurations.

Sample Configuration

"restendpoint": {
    "GenericBalanceTransferDetails" : {
      "servergroupid" : "BillingCare"
    }
}

Input Request

Table 6-5 describes the parameters accepted in the XML input request.

Table 6-5 Input Request Parameters

Notification Type	Mandatory/Optional	Description
operation	Mandatory	Operation name for the request which is configured.
type	Optional	If present, it will override the type present in the config for the operation.
endPoint	Optional	If present, it will override the endpoint present in the config for the operation.
requestDetails	Mandatory for POST/PUT	For GET, requestDetails will not be sent to the REST server. For POST/PUT, XML request will be converted to JSON and sent as body in the OUTPUT request.
arrayXmlTags	Optional	Tags that need to be converted to array type in JSON request. Multiple tags can be used with comma separator. Example: <arrayXmlTags>bundles,package</arrayXmlTags>

Sample XML Request

<operation>GenericRequest</operation><requestDetails>    
<msisdn>923450010213</msisdn> <package> <packageType>Addon</packageType>
<bundles> <bundleName>500001</bundleName> </bundles>    
</package></requestDetails> <arrayXmlTags>bundles,package</arrayXmlTags>

Sample JSON Converted Request

JSON Request{
    "arrayXmlTags": "bundles,package",
    "requestDetails": {
        "package": [{
            "bundles": [{"bundleName": 500001}],
            "packageType": "Addon"
        }],
        "msisdn": 923450010213
    },
    "operation": "GenericRequest"
}

Sample XML Input Request

This example shows a GET request for balance transfer audit object using Generic request Handler.

<operation>GenericBalanceTransferDetails</operation>
<endPoint>http://hostname:port/bcws/webresources/v1.0/billunits/balancegroups/transferbalance/0.0.0.1+-event-audit-transfer_balance+335887608146194890</endPoint>
<type>GET</type>

where, hostname and port is the hostname and port of the machine where REST server is running.

REST Request Parameters

{
    "endPoint": "http://hostname:port/bcws/webresources/v1.0/billunits/balancegroups/transferbalance/0.0.0.1+-event-audit-transfer_balance+335887608146194890",
    "type": "GET",
    "operation": "GenericBalanceTransferDetails"
}

REST API Response

Tags present in the response will not be validated. JSON message will be directly converted to XML.

Sample REST API Response

{
"extension":null,
"id":"0.0.0.1+-event-audit-transfer_balance+335887608146194890",
"sourceAccountRef":{
"id":"0.0.0.1+-account+37201",
"uri":"http://hostname:port/bcws/webresources/v1.0/accounts/0.0.0.1+-account+37201"
},
"targetAccountRef":{
"id":"0.0.0.1+-account+34057",
"uri":"http://hostname:port/bcws/webresources/v1.0/accounts/0.0.0.1+-account+34057"
},
"transferDate":1649681472000,
"sourceRef":{
"id":"0.0.0.1+-balance_group+40785",
"type":"balanceGroup"
},
"targetRef":{
"id":"0.0.0.1+-balance_group+34953",
"type":"balanceGroup"
},
"transferAmount":11,
"transferAmountType":840,
"chargeSource":false,
"chargeDestination":true,
"sourceImpactedBucket":[{"validFrom":1647993600000,"validTo":0,"amount":11}],
"targetImpactedBucket":[{"validFrom":1647993600000,"validTo":0,"amount":-11}],
"sourceTransferFee":null,
"targetTransferFee":{
"amount":3,
"feeTax":0.6,
"resourceId":840
}
}

XML Response

Sample XML Response

<targetRef>
<id>0.0.0.1+-balance_group+34953</id>
<type>balanceGroup</type>
</targetRef>
<extension>null</extension>
<targetImpactedBucket>
<amount>-11</amount>
<validFrom>1647993600000</validFrom>
<validTo>0</validTo>
</targetImpactedBucket>
<chargeSource>false</chargeSource>
<targetTransferFee>
<amount>3</amount>
<resourceId>840</resourceId>
<feeTax>0.6</feeTax>
</targetTransferFee>
<transferAmount>11</transferAmount>
<sourceTransferFee>null</sourceTransferFee>
<targetAccountRef>
<id>0.0.0.1+-account+34057</id>
<uri>http://hostname:port/bcws/webresources/v1.0/accounts/0.0.0.1+-account+34057</uri>
</targetAccountRef>
<transferAmountType>840</transferAmountType>
<transferDate>1649681472000</transferDate>
<chargeDestination>true</chargeDestination>
<id>0.0.0.1+-event-audit-transfer_balance+335887608146194890</id>
<sourceAccountRef>
<id>0.0.0.1+-account+37201</id>
<uri>http://hostname:port/bcws/webresources/v1.0/accounts/0.0.0.1+-account+37201</uri>
</sourceAccountRef>
<sourceRef>
<id>0.0.0.1+-balance_group+40785</id>
<type>balanceGroup</type>
</sourceRef>
<sourceImpactedBucket>
<amount>11</amount>
<validFrom>1647993600000</validFrom>
<validTo>0</validTo>
</sourceImpactedBucket>
<rest_status_code>200</rest_status_code>