API Description for Extended Web Services

Content-Based Charging

The following section provides detailed information about the content-based charging service capability.

 

---

Web Service

Content based charging makes it possible to charge a subscriber for the content of the service rather than, for example, duration of a call. Charging data records (CDRs) can be generated immediately or in parts. It is also possible to add and reserve amounts to and from accounts.

The Content based charging Web Service provides an application with functions for

• Debit and credit an account
• Debit and credit an account in real time (directly)
• Reserve an amount from an account
• Get amount left of reserved amount

close

Close the content based charging session.

Table 6-1 close(chargingSessionTicket)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
Returns
-
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

createChargingSession

Creates a charging session related to the specified user, the charging merchant, and the charging account as well as to the application invoking this method.

Must be invoked before any reservations, credits, or debits can be done.

Table 6-2 createChargingSession(merchantId, accountId, address, corrId, serviceCode, requesterId)

Parameter Name	Type	Description
Input
merchantId	xsd:string	The charging merchant ID.
accountId	xsd:int	The charging account ID.
address	xsd:string	The address of the subscriber to set data in the profile for. Must be synchronized with the parameter addressPlan.
corrId	impl:CorrelationID	This value can be used to correlate the charging to network activity. See CorrelationID.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
createChargingSessionReturn	impl:ChargingSessionID	See ChargingSessionID.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

creditAmountWait

Credit (add) an amount of a certain currency to an existing reservation.

Table 6-3 creditAmountWait(chargingSessionTicket, amount, currency, description, requestNumber, releaseAmount)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
amount	xsd:float	The amount to credit.
currency	xsd:string	The currency of the amount to credit. This has to be specified by a three letter combination, according to ISO-4217:1995, "Codes for the representation of currencies and funds".Examples: DEM, EUR, USD.
description	xsd:string	Descriptive text for informational purpose that is,. text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
releaseAmount	xsd:boolean	If set to true, this parameter indicates that the reservation can be freed.
Returns
creditAmountWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

creditUnitWait

Credit (add) an amount of a certain unit type to an existing reservation.

Table 6-4 creditUnitWait(chargingSessionTicket, volumes, description, requestNumber, releaseUnit)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
volumes	impl:ArrayOfVolume	See ArrayOfVolume.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:	Specifies the number given in the result of the previous operation on this session, or when creating the session.
releaseUnit	xsd:boolean	If set to true, this parameter indicates that the reservation can be freed.
Returns
creditUnitWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

debitAmountWait

Debit (withdraw) an amount of a certain currency to an existing reservation.

Table 6-5 debitAmountWait(chargingSessionTicket, amount, currency, description, requestNumber, releaseAmount)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
amount	xsd:float	The amount to debit.
currency	xsd:string	The currency of the amount to credit. This has to be specified by a three letter combination, according to ISO-4217:1995, "Codes for the representation of currencies and funds". Examples: DEM, EUR, USD.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
releaseAmount	xsd:boolean	If set to true, this parameter indicates that the reservation can be freed.
Returns
debitAmountWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

debitUnitWait

Debit (withdraw) an amount of a unit type to an existing reservation.

Table 6-6 debitUnitWait(chargingSessionTicket, volumes, description, requestNumber, releaseUnit)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
volumes	impl:ArrayOfVolume	See ArrayOfVolume.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
releaseUnit	xsd:boolean	If set to true, this parameter indicates that the reservation can be freed.
Returns
debitUnitWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

directCreditAmountWait

Credit (add) an amount, of a certain currency, directly to a user's account. If a reservation has been made, it will not be influenced.

Table 6-7 directCreditAmountWait(chargingSessionTicket, amount, currency, description, requestNumber)

Parameter Name	Type	Description
Parameter
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
amount	xsd:float	The amount to credit.
currency	xsd:string	The currency of the amount to credit. This has to be specified by a three letter combination, according to ISO-4217:1995, "Codes for the representation of currencies and funds". Examples: DEM, EUR, USD.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
Returns
directCreditAmountWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

directCreditUnitWait

Credit (add) an amount, of a certain unit type, directly to a user's account. If a reservation has been made, it will not be influenced.

Table 6-8 directCreditUnitWait(chargingSessionTicket, volumes, description, requestNumber)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
volumes	impl:ArrayOfVolume	See ArrayOfVolume.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
Returns
directCreditUnitWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

directDebitAmountWait

Debit (withdraw) an amount, of a certain currency, directly from a user's account. If a reservation has been made, it will not be influenced.

Table 6-9 directDebitAmountWait(chargingSessionTicket, amount, currency, description, requestNumber)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
amount	xsd:float	The amount to debit.
currency	xsd:string	The currency of the amount to debit. This has to be specified by a three letter combination, according to ISO-4217:1995, "Codes for the representation of currencies and funds". Examples: DEM, EUR, USD.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
Returns
directDebitAmountWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

directDebitUnitWait

Debit (withdraw) an amount of a certain unit type directly from a user's account. If a reservation has been made, it will not be influenced.

Table 6-10 directDebitUnitWait(chargingSessionTicket, volumes, description, requestNumber)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
volumes	impl:ArrayOfVolume	See ArrayOfVolume.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
Returns
directDebitUnitWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

getAmountLeftWait

Get information on the value of the remaining amount of the reservation.

Table 6-11 getAmountLeftWait(chargingSessionTicket)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
Returns
getAmountLeftWaitReturn	xsd:float	Amount left in the reservation.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

getSessionId

Return a unique ID for this charging session that can be used as a transaction ID in the application when using a reservation.

This can be used, for example, for a final end user purchase confirmation.

Table 6-12 getSessionId(chargingSessionTicket)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
Returns
getSessionIdReturn	xsd:string	Session ID.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

getUnitLeftWait

Get information on the value of the remaining units of the reservation.

Table 6-13 getUnitLeftWait(chargingSessionTicket)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
Returns
getUnitLeftWaitReturn	impl:ArrayOfVolume	See ArrayOfVolume.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

rateRequestWait

Request rates for given charging parameters.

Table 6-14 rateRequestWait(chargingSessionTicket, chargingParameters)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
chargingParameters	impl:ArrayOfChargingParameter	See ArrayOfChargingParameter.
Returns
rateRequestWaitReturn	impl:RateResult	See RateResult.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

reserveAmountWait

Reserve an amount, of a certain currency, from a user's account to be used exclusively in this charging session. A reservation has a lifetime for which it is valid.

If invoked more than once, the reservation will be extended to match the total amount in the reservations. This will also re-initialize the reservation lifetime.

Table 6-15 reserveAmountWait(chargingSessionTicket, amount, currency, description, requestNumber)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
amount	xsd:float	The amount to reserve.
currency	xsd:string	The currency of the amount to reserve. This has to be specified by a three letter combination, according to ISO-4217:1995, "Codes for the representation of currencies and funds". Examples: DEM, EUR, USD.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
Returns
reserveAmountWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

reserveUnitWait

Reserve an amount, of a certain unit type, from a user's account to be used exclusively in this charging session. A reservation has a lifetime for which it is valid.

If invoked more than once, the reservation will be extended to match the total amount in the reservations. This will also re-initialize the reservation lifetime.

Table 6-16 reserveUnitWait(chargingSessionTicket, volumes, description, requestNumber)

Parameter Name	Type	Description
Input
chargingSessionTicket	xsd:string	ID of the content based charging session, retrieved when it was created. See createChargingSession.
volumes	impl:ArrayOfVolume	See ArrayOfVolume.
description	xsd:string	Descriptive text for informational purpose. That is, text presented on the bill and used in communication towards the user.
requestNumber	xsd:int	Specifies the number given in the result of the previous operation on this session, or when creating the session.
Returns
reserveUnitWaitReturn	xsd:int	Request number. This number shall be used as inparameter in the next request in the charging session.
Exception
ContentBasedChargingException		See ContentBasedChargingException.
GeneralException		See GeneralException.

Exceptions

ContentBasedChargingException

Exception of this type are raised when there are error conditions related to the Content Based Charging Web Service. Other error conditions are reported using GeneralException.

GeneralException

This exception is raised when the applications session has expired or there are communication problems with the underlying platform.

Complex data types

CorrelationID

This value can be used to correlate the charging to network activity.

Table 6-17

Name	Type	Description
correlation	xsd:int	ID of the correlation.
corrType	xsd:int	Type of correlation.

ChargingSessionID

Holder for chargingTicket and initial request number.

Table 6-18

Name	Type	Description
chargingTicket	xsd:string	Identifier for the charging session.
initialRequestNumber	xsd:int	Request number to be used as inparameter in the first charging operation.

ArrayOfVolume

Table 6-19

Name	Type	Description
Array of Volume		See Volume.

Volume

Holder for amount and unit. Either one is used.

Table 6-20

Name	Type	Description
amount	xsd:float	Amount to be used.
unit	xsd:int	Number representing the units to be used. 0 means undefined 1 means number 2 means octets 3 means seconds 4 means minutes 5 means hours 6 means days

ArrayOfChargingParameter

Table 6-21

Name	Type	Description
ArrayofChargingParameter		See ChargingParameter.

ChargingParameter

Holder for the value.

Table 6-22

Name	Type	Description
parameterId	xsd:int	ID of the parameter.
chargingPValue	impl:ChargingParameterValue	See ChargingParameterValue.

ChargingParameterValue

Defines datatype and value of the parameter. Either one is used.

Table 6-23

Name	Type	Description
intValue	xsd:int	Value given as an int.
floatValue	xsd:float	Value given as a float.
booleanValue	xsd:boolean	Value given as a boolean.
stringValue	xsd:string	Value given as a string.

RateResult

Holder of results from rating requests.

Table 6-24

Name	Type	Description
rates	impl:PriceVolume	See PriceVolume.
validityTimeLeftMs	xsd:int	Defines for how long the rate is valid. Given in milliseconds.

PriceVolume

Defines datatype and value of the parameter. If amount is used, currency is also used.

Table 6-25

Name	Type	Value
amount	xsd:float	The amount.
currency	xsd:string	The currency used in the parameter amount.
unitVolume	impl:Volume	See Volume.