3GPP TS V7.1.0 ( )

Transcription

1 TS V7.1.0 ( ) Technica Specification 3rd Generation Partnership Project; Technica Specification Group Core Network and Terminas; Open Service Access (OSA); Paray X Web Services; Part 7: Account management (Reease 7) The present document has been deveoped within the 3 rd Generation Partnership Project ( TM ) and may be further eaborated for the purposes of. The present document has not been subject to any approva process by the Organizationa Partners and sha not be impemented. This Specification is provided for future deveopment work within ony. The Organizationa Partners accept no iabiity for any use of this Specification. Specifications and reports for impementation of the TM system shoud be obtained via the Organizationa Partners' Pubications Offices.

2 Reease 7T 2 TS V7.1.0 ( ) Keywords UMTS, network, API, OSA Posta address support office address 650 Route des Lucioes - Sophia Antipois Vabonne - FRANCE Te.: Fax: Internet Copyright Notification No part may be reproduced except as authorized by written permission. The copyright and the foregoing restriction extend to reproduction in a media. 2006, Organizationa Partners (ARIB, ATIS, CCSA, ETSI, TTA, TTC). A rights reserved.

3 Reease 7T 3 TS V7.1.0 ( ) Contents Foreword...5 Introduction Scope References Definitions and abbreviations Definitions Abbreviations Detaied service description Namespaces Sequence diagrams Prepaid account recharge using a voucher Prepaid account recharge using direct payment XML Schema data type definition DatedTransaction structure Baance structure BaanceExpireDetais structure AccountChangedEvent enumeration Web Service interface definition Interface: AccountManagement Operation: GetBaance Input message: GetBaanceRequest Output message: GetBaanceResponse Referenced fauts Operation: GetCreditExpiryDate Input message: GetCreditExpiryDateRequest Output message: GetCreditExpiryDateResponse Referenced fauts Operation: BaanceUpdate Input message: BaanceUpdateRequest Output message: BaanceUpdateResponse Referenced fauts Operation: VoucherUpdate Input message: VoucherUpdateRequest Output message: VoucherUpdateResponse Referenced Fauts Operation: GetHistory Input message: GetHistoryRequest Output message: GetHistoryResponse Referenced fauts Operation: GetBaanceTypes Input message: GetBaanceTypesRequest Output message: GetBaanceTypesResponse Referenced fauts Interface: AccountManagementNotificationManager Operation: startnotification Input message: startnotificationrequest Output message: startnotificationresponse Referenced fauts Operation: endnotification Input message: endnotificationrequest Output message: endnotificationresponse... 15

4 Reease 7T 4 TS V7.1.0 ( ) Referenced fauts Interface: AccountNotification Operation: accountcharged Input message: accountchargedrequest Output message: accountchargedresponse Referenced fauts Operation: accountrecharged Input message: accountrechargedrequest Output message: accountrechargedresponse Referenced fauts Operation: accountlow Input message: accountlowrequest Output message: accountlowresponse Referenced fauts Faut definitions Faut: ServiceException End user authentication faied Unknown Voucher Faut: PoicyException Vouchers not accepted Service poicies...18 Annex A (normative): WSDL for Account Management...19 Annex B (informative): Change history...20

5 Reease 7T 5 TS V7.1.0 ( ) Foreword This Technica Specification has been produced by the 3 rd Generation Partnership Project (). acknowedges the contribution of the Paray X Web Services specifications from The Paray Group. The Paray Group is peased to see acknowedge and pubish the present document, and the Paray Group ooks forward to working with the community to improve future versions of the present document. The contents of the present document are subject to continuing work within the TSG and may change foowing forma TSG approva. Shoud the TSG modify the contents of the present document, it wi be re-reeased by the TSG with an identifying change of reease date and an increase in version number as foows: Version x.y.z where: x the first digit: 1 presented to TSG for information; 2 presented to TSG for approva; 3 or greater indicates TSG approved document under change contro. y the second digit is incremented for a changes of substance, i.e. technica enhancements, corrections, updates, etc. z the third digit is incremented when editoria ony changes have been incorporated in the document. Introduction The present document is part 7 of a muti-part deiverabe covering the 3 rd Generation Partnership Project; Technica Specification Group Core Network and Terminas; Open Service Access (OSA); Paray X Web Services, as identified beow: Part 1: Part 2: Part 3: Part 4: Part 5: Part 6: Part 7: Part 8: Part 9: Part 10: Part 11: Part 12: Part 13: Part 14: Part 15: Part 16: Part 17: Part 18: Part 19: Part 20: "Common" "Third party ca" "Ca Notification" "Short Messaging" "Mutimedia Messaging" "Payment" "Account management" "Termina Status" "Termina ocation" "Ca handing" "Audio ca" "Mutimedia conference" "Address ist management" "Presence" "Message Broadcast" "Geocoding" "Appication-driven Quaity of Service (QoS)" "Reserved" "Mutimedia streaming contro" "Mutimedia muticast contro"

6 Reease 7T 6 TS V7.1.0 ( ) 1 Scope The present document is Part 7 of the Stage 3 Paray X Web Service specification for Open Service Access (OSA). The OSA specifications define an architecture that enabes appication deveopers to make use of network functionaity through an open standardized interface, i.e. the OSA APIs. The concepts and the functiona architecture for the OSA are contained in TS [3]. The requirements for OSA are contained in TS [2]. The present document specifies the Account Management Web Service aspects of the interface. A aspects of the Account Management Web Service are defined here, these being: Name spaces. Sequence diagrams. Data definitions. Interface specification pus detaied method descriptions. Faut definitions. Service poicies. WSDL of the interfaces. The present document has been defined jointy between TSG CT WG5, ETSI TISPAN and The Paray Group. 2 References The foowing documents contain provisions which, through reference in this text, constitute provisions of the present document. References are either specific (identified by date of pubication, edition number, version number, etc.) or non-specific. For a specific reference, subsequent revisions do not appy. For a non-specific reference, the atest version appies. In the case of a reference to a document (incuding a GSM document), a non-specific reference impicity refers to the atest version of that document in the same Reease as the present document. [1] TR : "Vocabuary for Specifications". [2] TS : "Service Requirement for the Open Services Access (OSA); Stage 1". [3] TS : "Open Service Access (OSA); Stage 2". 4] TS : "Service aspects; Service principes". [5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". NOTE: Avaiabe at [6] TS : "Open Service Access (OSA); Paray X Web Services; Part 1: Common". 3 Definitions and abbreviations 3.1 Definitions For the purposes of the present document, the terms and definitions given in TS [6] appy.

7 Reease 7T 7 TS V7.1.0 ( ) 3.2 Abbreviations For the purposes of the present document, the abbreviations given in TS [6] appy. 4 Detaied service description Pre-paid subscribers, whether they have subscribed to pre-paid teephony, SMS, or data service, have credits with their service providers; the consumption of services wi ead to reduction of their credit, or the credit may expire. Therefore, from time to time, subscribers may have to recharge their accounts. This occurs through an appication that interfaces with the subscriber either directy or indirecty. Exampes of direct interaction are voice prompts and WAP/web pages, or even SMS. Typicay, such muti-moda appications either request a currency amount and, e.g. credit card information, or a voucher number pus credentias. The voucher number and credentias are then vaidated and causes a pre-determined currency amount to be transferred. The Paray X Account Management API described in the present document supports account querying, direct recharging and recharging through vouchers. As a side effect, it may prevent subscribers from having their account baance credits expire. 5 Namespaces The AccountManagement interface uses the namespace: The AccountManagementNotification interface uses the namespace: account_management /notification/v3_0 The AccountManagementNotificationManager interface uses the namespace: account_management /notification_manager/v3_0 The data types are defined in the namespace: The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema [5]. The use of the name 'xsd' is not semanticay significant.

8 Reease 7T 8 TS V7.1.0 ( ) 6 Sequence diagrams This subcause discusses three scenarios; one where a subscriber uses a voucher, one where the subscriber directy recharges after the payment is ceared, and one where the subscriber checks the recent transactions. NOTE: Associated Account Management API messages are shown in 'bod' format: e.g. (getbaance). 6.1 Prepaid account recharge using a voucher The prepaid subscriber wishes to recharge their account with a voucher and query their account baance. The subscriber uses their mobie phone or other wireine phone to interact with an IVR system. In order to recharge their account, the subscriber must enter the voucher number, the MSISDN to be recharged, and PIN(s). The IVR system accesses an externa voucher database to vaidate the voucher number. The subscriber's account baance is then increased with the vaue of the voucher (voucherupdate). The subscriber queries their account baance (getbaance), before and/or after the recharge. : End User : IVR : Payment Web Service Log on to IVR Enter voucher information Update voucher Acknowedge receipt Request baance Get baance Baance Pay baance message Figure 1

9 Reease 7T 9 TS V7.1.0 ( ) 6.2 Prepaid account recharge using direct payment Directy recharging (i.e. without a voucher) works much aong the same way. In this case, we assume the prepaid subscriber interacts with a web page. After providing the MSISDN, aong with the PIN, the user can query the account baance (getbaance). For recharging, the subscriber must enter payment detais, for exampe credit card information, from which the payment wi be made. After cearing the payment detais, the currency amount wi be transferred and the subscriber's prepaid account baance expiration date wi be reset (baanceupdate). The subscriber aso queries their account baance expiration date (getcreditexpirydate), after the recharge. : End User : Sef Serve Porta : Payment Web Service Log on to porta Request baance Get baance Baance Dispay account status Input recharge information Update baance Dispay account status Request credit expiry date Get credit expiry date Expiry date Dispay expiry date Log off Figure 2

10 Reease 7T 10 TS V7.1.0 ( ) 7 XML Schema data type definition 7.1 DatedTransaction structure This data structure represents a transaction record. Eement Name Eement Type Optiona TransactionDate xsd:datetime No The date the transaction occurred. TransactionDetais xsd:string No The transaction detais. 7.2 Baance structure This data structure represents a baance record. Eement Eement Optiona Name Type BaanceType xsd:string No Identifies the type of baance. End user accounts may have one or more baances for different types of usage (e.g Voice, SMS, gaming etc) Amount xsd:decima No Amount of baance 7.3 BaanceExpireDetais structure This data structure represents baance expiry detais. Eement Eement Optiona Name Type BaanceType xsd:string No Identifies the type of baance. End user accounts may have one or more baances for different types of usage (e.g Voice, SMS, gaming etc) Date xsd:datetime Yes It is the date the identified baance wi expire. Do not specify if the baance does not expire 7.4 AccountChangedEvent enumeration List of possibe account changed event vaues. Enumeration vaue Charge Recharge AccountLow A baance associated with the account is charged A baance associated with the account is recharged A baance associated with the account is beow the baance threshod 8 Web Service interface definition 8.1 Interface: AccountManagement The Account Management interface provides access to account information for update and query operations Operation: GetBaance This message resuts in getting account baances indicated by the end user identifier and associated end user PIN. The returned amount for each baance is specified as a currency amount.

11 Reease 7T 11 TS V7.1.0 ( ) End users accounts may have a singe baance for a usage, or may have mutipe baances for different uses. For exampe, an end user may have a separate baance for voice cas, SMS messages, and GPRS usage Input message: GetBaanceRequest Part name Part type Optiona EndUserIdentifier xsd:anyuri No This parameter identifies the end user's account. EndUserPin xsd:string Yes Contains the end user's credentias for authorizing access to the account Output message: GetBaanceResponse Part name resut Part type Baance [1 unbounded] Optiona No It is a Baance array that consists of types with a string and a decima fied i.e. the baance type and baance amount respectivey Referenced fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue. SVC End user authentication faied. PoicyException from TS [6]: POL Poicy error Operation: GetCreditExpiryDate This message resuts in getting the expiration date of the credit indicated by the end user identifier and associated end user PIN. The returned date is the date the current baance wi expire Input message: GetCreditExpiryDateRequest Part name Part type Optiona EndUserIdentifier xsd:anyuri No This parameter identifies the end user's account. EndUserPin xsd:string Yes Contains the end user's credentias for authorizing access to the account Output message: GetCreditExpiryDateResponse Part name resut Part type BaanceExpireDetais [1 unbounded] Optiona No It is a BaanceExpireDetais array that consists of types with a string and a date fied. i.e. Baance type and date baance wi expire respectivey Referenced fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue.

12 Reease 7T 12 TS V7.1.0 ( ) SVC End user authentication faied. PoicyException from TS [6]: POL Poicy error Operation: BaanceUpdate This message resuts in directy recharging the account indicated by the end user identifier and optiona associated end user PIN. The reference code is used to uniquey identify the request; it is the appication's responsibiity to provide a unique reference code within the scope of the appication. The baance type identifies an existing baance type in the account, or a new baance type to be added to the account. NOTE: getbaancetypes operation is used to discover the set of aowed baance types that can be associated with a specific end user s account. The recharge is specified as a currency amount. The baance is requested to expire in the number of days indicated by the period parameter. The operator's poicies may overrue this parameter. If the optiona period parameter is not present, the operator's poicy on baance expiration is aways in effect Input message: BaanceUpdateRequest Part name Part type Optiona EndUserIdentifier xsd:anyuri No This parameter identifies the end user's account. EndUserPin xsd:string Yes Contains the end user's credentias for authorizing access to the account. ReferenceCode xsd:string No Textua information to uniquey identify the request, e.g. in case of disputes BaanceType xsd:string No Identifies the type of baance to be recharged. An end user s account may have a baance for each type of usage (e.g. Voice, SMS, gaming etc) Amount xsd:decima No Currency amount that shoud be added to the baance identified in the BaanceType part. Period xsd:int Yes The baance is requested to expire in the number of days indicated by this parameter. The operator's poicies may overrue this parameter. If this optiona parameter is not present, the operator's poicy on baance expiration is aways in effect Output message: BaanceUpdateResponse Part name Part type Optiona None Referenced fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue. SVC End user authentication faied. PoicyException from TS [6]: POL Poicy error

13 Reease 7T 13 TS V7.1.0 ( ) Operation: VoucherUpdate This message resuts in directy recharging the account indicated by the end user identifier and optiona associated end user PIN. The reference code is used to uniquey identify the request; it is the appication's responsibiity to provide a unique reference code within the scope of the appication. A voucher identifier indirecty specifies the charge. The optiona voucher PIN code can be used to verify the voucher Input message: VoucherUpdateRequest Part name Part type Optiona EndUserIdentifier xsd:anyuri No This parameter identifies the end user's account. EndUserPin xsd:string Yes Contains the end user's credentias for authorizing access to the account. ReferenceCode xsd:string No Textua information to uniquey identify the request, e.g. in case of disputes VoucherIdentifier xsd:string No This parameter identifies the voucher. VoucherPin xsd:string Yes Contains the voucher's credentias for authentication Output message: VoucherUpdateResponse Part name Part type Optiona None Referenced Fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue. SVC End user authentication faied. SVC Unknown voucher. PoicyException from TS [6]: POL Poicy error. POL Vouchers not accepted Operation: GetHistory This message resuts in returning the transaction history of the account indicated by the end user identifier and associated optiona end user PIN. The maximum number of entries to return and the start date define the range of transactions that are of interest to the requester. If the tota number of entries in the transaction history, starting at the specified date, is arger than the specified maximum number of entries, ony the most recent events are returned. Note that the operator might imit the maximum amount of entries to be returned or the period for which the entries are to be returned.

14 Reease 7T 14 TS V7.1.0 ( ) Input message: GetHistoryRequest Part name Part type Optiona EndUserIdentifier xsd:anyuri No This parameter identifies the end user's account. EndUserPin xsd:string Yes Contains the end user's credentias for authorizing access to the account. Date xsd:datetime Yes This parameter indicates the desired starting date for the entries to be returned. If this parameter is not present, it is up to the discretion of the service to decide this date. MaxEntries xsd:int Yes This parameter indicates the maximum number of entries that sha be returned. If this parameter is not present, it is up to the discretion of the service to decide how many entries to return Output message: GetHistoryResponse Part Part type name resut DatedTransaction [0.. unbounded] Optiona Yes It is a DatedTransaction array that consists of types with a date fied and a string fied: i.e. the date of the occurrence and the transaction detais, respectivey Referenced fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue. PoicyException from TS [6]: POL Poicy error Operation: GetBaanceTypes This operation is used to discover the set of a possibe baance types that are permitted for a specified end user s account Input message: GetBaanceTypesRequest Part name Part type Optiona EndUserIdentifier xsd:anyuri No This parameter identifies the end user's account. EndUserPin xsd:string Yes Contains the end user's credentias for authorizing access to the account Output message: GetBaanceTypesResponse Part name resut Part type xsd:string [1 unbounded] Optiona No Identifies a the baance types that are permitted for this end user s account. An end user s account may have one or more baances for different types of usage (e.g Voice, SMS, gaming etc) Referenced fauts ServiceException from TS [6]:

15 Reease 7T 15 TS V7.1.0 ( ) SVC Service error. SVC Invaid input vaue. SVC End user authentication faied. PoicyException from TS [6]: POL Poicy error. 8.2 Interface: AccountManagementNotificationManager Set up notifications for account changes Operation: startnotification Notifications of account changes are made avaiabe to appications. The correator provided in the reference must be unique for this Web Service at the time the notification is initiated, otherwise a ServiceException (SVC0005) wi be returned to the appication. The enduseridentifier is the end user's account to monitor. The criteria provide the fitering condition to make notifications to the appication. The baancetypes part identifies baances for different types of usage within an account (e.g. Voice, SMS, gaming etc) Input message: startnotificationrequest Part name Part type Optiona reference common:simpereference No Notification endpoint definition enduseridentifie xsd:anyuri No Account to monitor r criteria AccountChangedEvent [0 unbounded] Yes List of account changed event vaues for which to generate notifications. If not present, notifications are enabed for a events. baancetypes xsd:string [0 unbounded] Yes Identifies the types of baance for which to generate notifications. If not present, notifications are enabed for each baance associated with the end user account Output message: startnotificationresponse Part name Part type Optiona None Referenced fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue. SVC0005- Dupicate correator. SVC End user authentication faied. PoicyException from TS [6]: POL Poicy error.

16 Reease 7T 16 TS V7.1.0 ( ) Operation: endnotification The appication may end a notification using this operation. Unti this operation returns, notifications may continue to be received by the appication Input message: endnotificationrequest Part name Part type Optiona correator xsd:string No Correator of request to end Output message: endnotificationresponse Part name Part type Optiona None Referenced fauts ServiceException from TS [6]: SVC Service error. SVC Invaid input vaue. PoicyException from TS [6]: POL Poicy error. 8.3 Interface: AccountNotification Notification interface to which notifications of account baance changes are deivered Operation: accountcharged When a monitored account baance is charged, a notification is deivered to the appication reporting the amount of the charge Input message: accountchargedrequest Part name Part type Optiona Correator xsd:string No Correator provided in request to set up this notification Amount xsd: decima No The currency amount of the charge baancetype xsd:string No The baance type that was charged Output message: accountchargedresponse Part name Part type Optiona None Referenced fauts None

17 Reease 7T 17 TS V7.1.0 ( ) Operation: accountrecharged When a monitored account baance is recharged, a notification is deivered to the appication reporting the amount of the recharge Input message: accountrechargedrequest Part name Part type Optiona Correator xsd:string No Correator provided in request to set up this notification Amount xsd: decima No The currency amount of the recharge baancetype xsd:string No The baance type that was recharged Output message: accountrechargedresponse Part name Part type Optiona None Referenced fauts None Operation: accountlow When a monitored account baance fas beow the ow baance threshod, a notification is deivered to the appication with the currency amounts of a baances associated with the account Input message: accountlowrequest Part name Part type Optiona Correator xsd:string No Correator provided in request to set up this notification Baance Baance No It is a set of Baance records, where each record specifies an account [1 unbounded] baance type and the associated currency amount Output message: accountlowresponse Part name Part type Optiona None Referenced fauts None

18 Reease 7T 18 TS V7.1.0 ( ) 9 Faut definitions 9.1 Faut: ServiceException End user authentication faied Name Message Id Text Variabes <SVC0250> End user authentication faied. None Unknown Voucher Name Message Id Text Variabes <SVC0251> Voucher %1 is not vaid. %1 Voucher identifier. 9.2 Faut: PoicyException Vouchers not accepted Name Message Id Text Variabes <POL0220> Vouchers not accepted. None. 10 Service poicies The foowing service poicies are defined for this service. Name Type VouchersAccepted xsd:booean Are vouchers accepted Currency xsd:string Currency used by service (per ISO 4217) LowBaance xsd:decima Threshod that triggers ow baance notification

19 Reease 7T 19 TS V7.1.0 ( ) Annex A (normative): WSDL for Account Management The document/itera WSDL representation of this interface specification is compiant to TS [6] and is contained in text fies (contained in archive docit.zip) which accompanies the present document.

20 Reease 7T 20 TS V7.1.0 ( ) Annex B (informative): Change history Change history Date TSG # TSG Doc. CR Rev Subject/Comment Cat Od New Jun 2006 CT_32 CP Add Notification Interface in Account Management B Dec 2006 CT_34 CP Correct the description of the getbaancetypes operation A Dec 2006 CT_34 CP Add baance type parts to the notification messages C