8 Web Service interface definition

29.199-063GPPOpen Service Access (OSA)Parlay X web servicesPart 6: PaymentTS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

8.1 Interface: AmountCharging

Charge operations by currency amount.

8.1.1 Operation: ChargeAmount

This message results in directly charging to the account indicated by the end user identifier. The charge is specified as a ChargingInformation, consisting of information on the amount to be charged and a description to appear on the bill and optionally references to individual operations relevant to the charging. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.1.1.1 Input message: ChargeAmountRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account to be charged
charge	parlayx_common_xsd:ChargingInformation	No	Information on the charge to be made. In the ChargingInformation the first entry of the Description list is information to appear on the bill, while additional entries (if any) can be references to individual operations relevant to the charging. The amount to be charged appears either directly in the amount-field or as code in the code-field. If both these two fields are missing or empty a service exception (SVC0007) will be thrown. The currency-field, if used, holds the currency to be used for the charging.
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes

8.1.1.2 Output message: ChargeAmountResponse

Part name	Part type	Optional	Description
None

8.1.1.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0007 – Invalid charging information
SVC0270 – Charge failed.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0012 – Too many description entries specified.

8.1.2 Operation: RefundAmount

This message results in directly applying a refund to the account indicated by the end user identifier. The refund is specified as a currency amount. The billing text field is used for textual information to appear on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.1.2.1 Input message: RefundAmountRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account to be refunded
charge	parlayx_common_xsd:ChargingInformation	No	Information on the charge to be refunded. In the ChargingInformation the first entry of the Description list is information to appear on the bill, while additional entries (if any) can be references to individual operations relevant to the refund. The charge to be refunded appears either directly in the amount-field or as code in the code-field. If both these two fields are missing or empty a service exception (SVC0007) will be thrown. The currency-field, if used, holds the currency to be used for the charging.
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes

8.1.2.2 Output message: RefundAmountResponse

Part name	Part type	Optional	Description
None

8.1.2.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0270 – Charge failed.
SVC0007 – Invalid charging information

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0012 – Too many description entries specified.

8.1.3 Operation: ChargeSplitAmount

This message results in directly charging to multiple accounts indicated by multiple end user identifiers simultaneously(e.g. multi-user games or conferences). Each account is specified by two parameters(endUserIdentifier and percent). The charge is specified as a ChargingInformation, consisting of information on the amount to be charged and a description to appear on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.1.3.1 Input message: ChargeSplitAmountRequest

Part name	Part type	Optional	Description
splitInfo	SplitType[1..unbounded]	No	Multiple sets of endUserIdentifier and percent element are specified
charge	parlayx_common_xsd:ChargingInformation	No	Information on the charge to be made. In the ChargingInformation the first entry of the Description list is information to appear on the bill, while additional entries (if any) can be references to individual operations relevant to the charging. The amount to be charged appears either directly in the amount-field or as code in the code-field. If both these two fields are missing or empty a service exception (SVC0007) will be thrown. The currency-field, if used, holds the currency to be used for the charging.
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes

8.1.3.2 Output message: ChargeSplitAmountResponse

Part name	Part type	Optional	Description
None

8.1.3.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0007 – Invalid charging information.
SVC0270 – Charge failed.
SVC0271 – Invalid sum of percentage allocations.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0012 – Too many description entries specified.
POL0250 – Too many endUserIdentifiers.
POL0251 – Split charging not supported

8.2 Interface: VolumeCharging

Charging operations by volume.

8.2.1 Operation: ChargeVolume

This message results in directly charging to the account indicated by the end user identifier. The charge is specified as a volume. The billing text field is used for textual information to appear on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.2.1.1 Input message: ChargeVolumeRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account to be charged
volume	xsd:long	No	The volume to be charged
billingText	xsd:string	No	Textual information to appear on the bill
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes
parameters	parlayx_common_xsd:NameValuePair [0..unbounded]	Yes	Parameters to use to perform rating ("unit", "contract", "service", "operation")

8.2.1.2 Output message: ChargeVolumeResponse

Part name	Part type	Optional	Description
None

8.2.1.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0270 – Charge failed.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.2.2 Operation: GetAmount

This message results in converting the given volume to a currency amount. The end user identifier is given to indicate the subscriber for whom this conversion calculation must be made. The message returns a currency amount if successful.

The following properties may be provided:

unit, specifying the unit used for measuring volume (e.g. bytes);
contract, number of a contract that may govern the use;
service, name of the service to be used (e.g. SendMultimediaMessage);
operation, name of the operation to be used (e.g. SendMessage).

8.2.2.1 Input message: GetAmountRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account to be charged
volume	xsd:long	No	The volume to be converted
parameters	parlayx_common_xsd:NameValuePair [0..unbounded]	Yes	Parameters to use to perform rating ("unit", "contract", "service", "operation")

8.2.2.2 Output message: GetAmountResponse

Part name	Part type	Optional	Description
result	parlayx_common_xsd:ChargingInformation	No	The conversion process results in the return of ChargingInformation where the description amount and currency fields must be filled.

8.2.2.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.2.3 Operation: RefundVolume

This message results in directly applying a refund to the account indicated by the end user identifier. The refund is specified as a volume. The billing text field is used for textual information to appear on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.2.3.1 Input message: RefundVolumeRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account to be refunded
volume	xsd:long	No	The volume to be refunded
billingText	xsd:string	No	Textual information to appear on the bill
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes
parameters	parlayx_common_xsd:NameValuePair [0..unbounded]	Yes	Parameters to use to perform rating ("unit", "contract", "service", "operation")

8.2.3.2 Output message: RefundVolumeResponse

Part name	Part type	Optional	Description
None

8.2.3.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0270 – Charge failed.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.2.4 Operation: ChargeSplitVolume

This message results in directly charging to multiple accounts indicated by multiple end user identifiers simultaneously(e.g. multi-user games or conferences). Each account is specified by two parameters(endUserIdentifier and percent). The charge is specified as a volume. The billing text field is used for textual information to appear on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.2.4.1 Input message: ChargeSplitVolumeRequest

Part name	Part type	Optional	Description
splitInfo	SplitType[1..unbounded]	No	Multiple sets of endUserIdentifier and percent element are specified
Volume	xsd:long	No	The volume to be charged
billingText	xsd:string	No	Textual information to appear on the bill
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes
Parameters	parlayx_common_xsd:NameValuePair [0..unbounded]	Yes	Parameters to use to perform rating ("unit", "contract", "service", "operation")

8.2.4.2 Output message: ChargeSplitVolumeResponse

Part name	Part type	Optional	Description
None

8.2.4.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0270 – Charge failed.
SVC0271 – Invalid sum of percentage allocations.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0250 – Too many endUserIdentifiers.
POL0251 – Split charging not supported.

8.3 Interface: ReserveAmountCharging

Operations to manage reservation charging by currency amount.

8.3.1 Operation: ReserveAmount

This message results in directly reserving an amount for an account indicated by the end user identifier. The reservation is specified as ChargingInformation. Note that reservations do not last forever; the duration of a reservation is defined by a service policy. If the reservation times out, the remaining funds will be returned to the account from which this reservation was made. However, the remaining funds shall preferably be returned explicitly to the account using the releaseReservation message. The first entry of the Description list of the ChargingInformation is used for textual information to appear on the bill. Subsequent textual information provided as first entry of the Description list during this charging session will be appended to this textual information; one charging session to a reservation will result in only one entry on the bill. In case of success, a reservation id is returned for future reference; e.g. subsequent charging against the existing reservation using the chargeReservation message.

8.3.1.1 Input message: ReserveAmountRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account subject to the reservation
charge	parlayx_common_xsd:ChargingInformation	No	Information on the charge to be reserved. In the ChargingInformation the first entry of the Description list is information to appear on the bill, while additional entries (if any) can be references to individual operations relevant to the charging.The charge to be reserved appears either directly in the amount-field or as code in the code-field. If both these two fields are missing or empty a service exception (SVC0007) will be thrown. The currency-field, if used, holds the currency to be used for the charging.

8.3.1.2 Output message: ReserveAmountResponse

Part name	Part type	Optional	Description
result	xsd:string	No	It is an identifier for the newly created reservation

8.3.1.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0007 – Invalid charging information

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0012 – Too many description entries specified.

8.3.2 Operation: ReserveAdditionalAmount

This message results in the addition/reduction of a currency amount to/from an existing reservation indicated by the reservation id. The reservation is specified as a currency amount. Note that reservations do not last forever; the duration of a reservation is defined by a service policy. Invoking this message will extend the current reservation enforcement time by the duration defined in the same service policy. The first entry of the Description list of ChargingInformation is used for appending textual information to appear on the bill. The textual information is appended to the initial textual information given in the first entry of the Description list by the reserveAmount message; one charging session to a reservation will result in only one entry on the bill. Reserved credit can be returned to the account through the releaseReservation message.

8.3.2.1 Input message: ReserveAdditionalAmountRequest

Part name	Part type	Optional	Description
reservationIdentifier	xsd:string	No	An identifier for the reservation to be amended
charge	parlayx_common_xsd:ChargingInformation	No	Information on the charge to be added to (or subtracted from) the reservation. In the ChargingInformation the first entry of the Description list is information to appear on the bill, while additional entries (if any) can be references to individual operations relevant to the charging.The charge to be reserved appears either directly in the amount-field or as code in the code-field. If both these two fields are missing or empty a service exception (SVC0007) will be thrown. The currency-field is not applicable: the currency is defined only when the reservation is established (i.e. the ReserveAmount operation is invoked).

8.3.2.2 Output message : ReserveAdditionalAmountResponse

Part name	Part type	Optional	Description
None

8.3.2.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0007 – Invalid charging information

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0012 – Too many description entries specified.

8.3.3 Operation: ChargeReservation

This message results in charging to a reservation indicated by the reservation id. Reservations, identified by reservation id, are established through invoking the reserveAmount message. The charge is specified as ChargingInformation. The first entry of the Descritoin list of the ChargingInformation is used for appending textual information to appear on the bill. The textual information is appended to the initial textual information given in the first entry of the Description list by the reserveAmount message; one charging session to a reservation will result in only one entry on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.3.3.1 Input message: ChargeReservationRequest

Part name	Part type	Optional	Description
reservationIdentifier	xsd:string	No	An identifier for the reservation to be charged
charge	parlayx_common_xsd:ChargingInformation	No	Information on the reservation to be charged. In the ChargingInformation the first entry of the Description list is information to appear on the bill, while additional entries (if any) can be references to individual operations relevant to the charging.The reserved amount to be charged appears either directly in the amount-field or as code in the code-field. If both these two fields are missing or empty a service exception (SVC0007) will be thrown. The currency-field is not applicable: the currency is defined only when the reservation is established (i.e. the ReserveAmount operation is invoked).
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes

8.3.3.2 Output message: ChargeReservationResponse

Part name	Part type	Optional	Description
None

8.3.3.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0007 – Invalid charging information
SVC0270 – Charge failed.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.
POL0012 – Too many description entries specified.

8.3.4 Operation: ReleaseReservation

Returns funds left in a reservation indicated by reservation id to the account from which this reservation was made. Reservations, identified by reservation id, are established by invoking the reserveAmount message.

8.3.4.1 Input message: ReleaseReservationRequest

Part name	Part type	Optional	Description
reservationIdentifier	xsd:string	No	An identifier for the reservation to be released

8.3.4.2 Output message: ReleaseReservationResponse

Part name	Part type	Optional	Description
None

8.3.4.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.4 Interface: ReserveVolumeCharging

Operations to manage reservation charging by volume amount.

8.4.1 Operation: GetAmount

Returns the amount resulting from converting the given volume. The end user identifier is given to indicate the subscriber for whom this calculation must be made. The message returns a currency amount if successful.

The following properties may be provided:

unit, specifying the unit used for measuring volume (e.g. bytes);
contract, number of a contract that may govern the use;
service, name of the service to be used (e.g. SendMultimediaMessage);
operation, name of the operation to be used (e.g. SendMessage).

8.4.1.1 Input message: GetAmountRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account to be charged
volume	xsd:long	No	The volume to be converted
parameters	parlayx_common_xsd:NameValuePair [0..unbounded]	Yes	Parameters to use to perform rating ("unit", "contract", "service", "operation")

8.4.1.2 Output message : GetAmountResponse

Part name

Part type

Optional

Description

result

parlayx_common_xsd:ChargingInformation

It is the currency amount resulting from the conversion process

The conversion process results in the return of ChargingInformation where the description amount and currency fields must be filled.

8.4.1.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.4.2 Operation: ReserveVolume

Reserves an amount of an account indicated by the end user identifier. The reservation is specified as a volume. Note that reservations do not last forever; the duration of a reservation is defined by a service policy. If the reservation times out, the remaining volume will be returned to the account from which this reservation was made. However, the remaining volume should preferably be returned explicitly to the account using the releaseReservation message. The billing text field is used for textual information to appear on the bill. Subsequent textual information provided during this charging session will be appended to this textual information; one charging session to a reservation will result in only one entry on the bill. In case of success, a reservation identifier is returned for future reference; e.g. subsequent charging against the existing reservation using the chargeReservation message.

8.4.2.1 Input message: ReserveVolumeRequest

Part name	Part type	Optional	Description
endUserIdentifier	xsd:anyURI	No	The end user’s account subject to the reservation
volume	xsd:long	No	The volume of the reservation
billingText	xsd:string	No	Textual information to appear on the bill
parameters	parlayx_common_xsd:NameValuePair [0..unbounded]	Yes	Parameters to use to perform rating ("unit", "contract", "service", "operation"). There is a maximum of one instance of each parameter type. Example, for the request "reserve 5 minutes of the gold video service", the volume part value is 5 and the parameters part has the following properties: "unit"=minutes "contract"=gold "service"=video

8.4.2.2 Output message: ReserveVolumeResponse

Part name	Part type	Optional	Description
result	xsd:string	No	It is an identifier for the newly created reservation

8.4.2.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.4.3 Operation: ReserveAdditionalVolume

Adds/reduces a volume to an existing reservation indicated by the reservation id. The reservation is specified as a volume. Note that reservations do not last forever; the duration of a reservation is defined by a service policy. Invoking this message will extend the current reservation enforcement time by the duration defined in the same service policy. The billing text field is used for appending textual information to appear on the bill. The textual information is appended to the initial textual information given by the reserveVolume message; one charging session to a reservation will result in only one entry on the bill. A reserved credit can be returned to the account through the releaseReservation message.

8.4.3.1 Input message: ReserveAdditionalVolumeRequest

Part name	Part type	Optional	Description
reservationIdentifier	xsd:string	No	An identifier for the reservation to be amended
volume	xsd:long	No	The volume to be added to (or subtracted from) the reservation. [Note the associated rating parameters are the same as those defined in the parameters part of the original ReserveVolumeRequest message.]
billingText	xsd:string	No	Textual information to appear on the bill

8.4.3.2 Output message: ReserveAdditionalVolumeResponse

Part name	Part type	Optional	Description
None

8.4.3.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.4.4 Operation: ChargeReservation

This message results in charging to a reservation indicated by the reservation id.. Reservations, identified by reservation id., are established through invoking the reserveVolume message. The charge is specified as a volume. Optionally, the billing text field can be used for appending textual information to appear on the bill. The textual information is appended to the initial textual information given by the reserveVolume message; one charging session to a reservation will result in only one entry on the bill. The reference code is used to uniquely identify the request; it is the application’s responsibility to provide a unique reference code within the scope of the application.

8.4.4.1 Input message: ChargeReservationRequest

Part name	Part type	Optional	Description
reservationIdentifier	xsd:string	No	An identifier for the reservation to be charged
volume	xsd:long	No	The volume to be charged. [Note the associated rating parameters are the same as those defined in the parameters part of the original ReserveVolumeRequest message.]
billingText	xsd:string	Yes	Textual information to appear on the bill
referenceCode	xsd:string	No	Textual information to uniquely identify the request, e.g. in case of disputes

8.4.4.2 Output message: ChargeReservationResponse

Part name	Part type	Optional	Description
None

8.4.4.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.
SVC0270 – Charge failed.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.

8.4.5 Operation: ReleaseReservation

Returns funds left in a reservation indicated by reservation id. to the account from which this reservation was made. Reservations, identified by reservation id., are established through invoking the reserveVolume message.

8.4.5.1 Input message: ReleaseReservationRequest

Part name	Part type	Optional	Description
reservationIdentifier	xsd:string	No	An identifier for the reservation to be released

8.4.5.2 Output message: ReleaseReservationResponse

Part name	Part type	Optional	Description
None

8.4.5.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

SVC0001 – Service error.
SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

POL0001 – Policy error.