1、 ETSI ES 202 391-7 V1.3.1 (2008-05)ETSI Standard Open Service Access (OSA);Parlay X Web Services;Part 7: Account Management(Parlay X 2)floppy3 ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 2 Reference RES/TISPAN-01056-07-OSA Keywords API, OSA, service ETSI 650 Route des Lucioles F-06921 Sophia Antipolis C
2、edex - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16 Siret N 348 623 562 00017 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88 Important notice Individual copies of the present document can be downloaded from: http:/www.etsi.org The present docu
3、ment may be made available in more than one electronic version or in print. In any case of existing or perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF). In case of dispute, the reference shall be the printing on ETSI printers of the
4、PDF version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or change of status. Information on the current status of this and other ETSI documents is available at http:/portal.etsi.org/tb/status/sta
5、tus.asp If you find errors in the present document, please send your comment to one of the following services: http:/portal.etsi.org/chaircor/ETSI_support.asp Copyright Notification No part may be reproduced except as authorized by written permission. The copyright and the foregoing restriction exte
6、nd to reproduction in all media. European Telecommunications Standards Institute 2008. The Parlay Group 2008. All rights reserved. DECTTM, PLUGTESTSTM, UMTSTM, TIPHONTM, the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members. 3GPPTM is a Trade Mark of ETS
7、I registered for the benefit of its Members and of the 3GPP Organizational Partners. ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 3 Contents Intellectual Property Rights5 Foreword.5 1 Scope 6 2 References 6 2.1 Normative references .6 3 Definitions and abbreviations.7 3.1 Definitions7 3.2 Abbreviations .
8、7 4 Detailed service description .7 5 Namespaces7 6 Sequence diagrams.7 6.1 Prepaid account recharge using a voucher .8 6.2 Prepaid account recharge using direct payment .8 7 XML Schema data type definition .10 7.1 DatedTransaction structure.10 7.2 Balance structure 10 7.3 BalanceExpireDetails struc
9、ture 10 8 Web Service interface definition10 8.1 Interface: AccountManagement .10 8.1.1 Operation: getBalance.10 8.1.1.1 Input message: getBalanceRequest .10 8.1.1.2 Output message: getBalanceResponse 11 8.1.1.3 Referenced faults.11 8.1.2 Operation: getCreditExpiryDate .11 8.1.2.1 Input message: get
10、CreditExpiryDateRequest11 8.1.2.2 Output message: getCreditExpiryDateResponse.11 8.1.2.3 Referenced faults.11 8.1.3 Operation: balanceUpdate.12 8.1.3.1 Input message: balanceUpdateRequest .12 8.1.3.2 Output message: balanceUpdateResponse 12 8.1.3.3 Referenced faults.12 8.1.4 Operation: voucherUpdate
11、12 8.1.4.1 Input message: voucherUpdateRequest.13 8.1.4.2 Output message: voucherUpdateResponse .13 8.1.4.3 Referenced Faults13 8.1.5 Operation: getHistory .13 8.1.5.1 Input message: getHistoryRequest 13 8.1.5.2 Output message: getHistoryResponse.14 8.1.5.3 Referenced faults.14 8.1.6 Operation: getB
12、alanceTypes.14 8.1.6.1 Input message: getBalanceTypesRequest .14 8.1.6.2 Output message: getBalanceTypesResponse 14 8.1.6.3 Referenced faults.14 9 Fault definitions15 9.1 ServiceException15 9.1.1 SVC0250: End user authentication failed.15 9.1.2 SVC0251: Unknown Voucher 15 9.2 PolicyException .15 9.2
13、.1 POL0220: Vouchers not accepted 15 10 Service policies 15 ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 4 Annex A (normative): WSDL for Account Management.16 Annex B (informative): Bibliography.17 History 18 ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 5 Intellectual Property Rights IPRs essential or potenti
14、ally essential to the present document may have been declared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: “Intellectual Property Rights (IPRs); Essential, or potentially Essential, I
15、PRs notified to ETSI in respect of ETSI standards“, which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web server (http:/webapp.etsi.org/IPR/home.asp). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guar
16、antee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document. Foreword This ETSI Standard (ES) has been produced by ETSI Technical Committee Telecommunications and
17、 Internet converged Services and Protocols for Advanced Networking (TISPAN). The present document is part 7 of a multi-part deliverable covering Open Service Access (OSA); Parlay X Web Services, as identified below: Part 1: “Common“; Part 2: “Third Party Call“; Part 3: “Call Notification“; Part 4: “
18、Short Messaging“; Part 5: “Multimedia Messaging“; Part 6: “Payment“; Part 7: “Account Management“; Part 8: “Terminal Status“; Part 9: “Terminal Location“; Part 10: “Call Handling“; Part 11: “Audio Call“; Part 12: “Multimedia Conference“; Part 13: “Address List Management“; Part 14: “Presence“. The p
19、resent document has been defined jointly between ETSI, The Parlay Group (http:/www.parlay.org) and the 3GPP. The present document forms part of the Parlay X 2.2 set of specifications. The present document is equivalent to 3GPP TS 29.199-07 V6.6.0 (Release 6). ETSI ETSI ES 202 391-7 V1.3.1 (2008-05)
20、6 1 Scope The present document is part 7 of the Stage 3 Parlay X 2 Web Services specification for Open Service Access (OSA). The OSA specifications define an architecture that enables application developers to make use of network functionality through an open standardized interface, i.e. the OSA API
21、s. The present document specifies the Account Management Web Service. The following are defined here: Name spaces. Sequence diagrams. Data definitions. Interface specification plus detailed method descriptions. Fault definitions. Service Policies. WSDL Description of the interfaces. 2 References Ref
22、erences are either specific (identified by date of publication and/or edition number or version number) or non-specific. For a specific reference, subsequent revisions do not apply. Non-specific reference may be made only to a complete document or a part thereof and only in the following cases: - if
23、 it is accepted that it will be possible to use all future changes of the referenced document for the purposes of the referring document; - for informative references. Referenced documents which are not found to be publicly available in the expected location might be found at http:/docbox.etsi.org/R
24、eference. For online referenced documents, information sufficient to identify and locate the source shall be provided. Preferably, the primary source of the referenced document should be cited, in order to ensure traceability. Furthermore, the reference should, as far as possible, remain valid for t
25、he expected life of the document. The reference shall include the method of access to the referenced document and the full network address, with the same punctuation and use of upper case and lower case letters. NOTE: While any hyperlinks included in this clause were valid at the time of publication
26、 ETSI cannot guarantee their long term validity. 2.1 Normative references The following referenced documents are indispensable for the application of the present document. For dated references, only the edition cited applies. For non-specific references, the latest edition of the referenced document
27、 (including any amendments) applies. 1 W3C Recommendation (2 May 2001): “XML Schema Part 2: Datatypes“. NOTE: Available at: http:/www.w3.org/TR/2001/REC-xmlschema-2-20010502/. ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 7 2 ETSI ES 202 391-1: “Open Service Access (OSA); Parlay X Web Services; Part 1: Co
28、mmon (Parlay X 2)“. 3 ISO 4217: “Codes for the representation of currencies and funds“. 3 Definitions and abbreviations 3.1 Definitions For the purposes of the present document, the terms and definitions given in ES 202 391-1 2 apply. 3.2 Abbreviations For the purposes of the present document, the a
29、bbreviations given in ES 202 391-1 2 apply. 4 Detailed service description Pre-paid subscribers, whether they have subscribed to pre-paid telephony, SMS, or data service, have credits with their service providers; the consumption of services will lead to reduction of their credit, or the credit may
30、expire. Therefore, from time to time, subscribers may have to recharge their accounts. This occurs through an application that interfaces with the subscriber either directly or indirectly. Examples of direct interaction are voice prompts and WAP/web pages, or even SMS. Typically, such multi-modal ap
31、plications either request a currency amount and, e.g. credit card information, or a voucher number plus credentials. The voucher number and credentials are then validated and causes a pre-determined currency amount to be transferred. The Parlay X 2 Account Management API described in the present doc
32、ument supports account querying, direct recharging and recharging through vouchers. As a side effect, it may prevent subscribers from having their account balance credits expire. 5 Namespaces The AccountManagement interface uses the namespace: http:/www.csapi.org/wsdl/parlayx/account_management/v2_3
33、 The data types are defined in the namespace: http:/www.csapi.org/schema/parlayx/account_management/v2_2 The “xsd“ namespace is used in the present document to refer to the XML Schema data types defined in XML Schema 1. The use of the name “xsd“ is not semantically significant. 6 Sequence diagrams T
34、his clause discusses three scenarios; one where a subscriber uses a voucher, one where the subscriber directly recharges after the payment is cleared, and one where the subscriber checks the recent transactions. NOTE: Associated Account Management API messages are shown in “bold“ format: e.g. (getBa
35、lance). ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 8 6.1 Prepaid account recharge using a voucher The prepaid subscriber wishes to recharge their account with a voucher and query their account balance. The subscriber uses their mobile phone or other wireline phone to interact with an IVR system. In ord
36、er to recharge their account, the subscriber must enter the voucher number, the MSISDN to be recharged , and PIN(s). The IVR system accesses an external voucher database to validate the voucher number. The subscribers account balance is then increased with the value of the voucher (voucherUpdate). T
37、he subscriber queries their account balance (getBalance), before and/or after the recharge. : End User : IVR : Payment Web ServiceLog on to IVREnter voucher informationUpdate voucherAcknowledge receiptRequest balanceGet balanceBalancePlay balance messageFigure 1 6.2 Prepaid account recharge using di
38、rect payment Directly recharging (i.e. without a voucher) works much along the same way. In this case, we assume the prepaid subscriber interacts with a web page. After providing the MSISDN, along with the PIN, the user can query the account balance (getBalance). For recharging, the subscriber must
39、enter payment details, for example credit card information, from which the payment will be made. After clearing the payment details, the currency amount will be transferred and the subscribers prepaid account balance expiration date will be reset (balanceUpdate). The subscriber also queries their ac
40、count balance expiration date (getCreditExpiryDate), after the recharge. ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 9 : End User : Self Serve Portal: Payment Web ServiceLog on to portalRequest balanceGet balanceBalanceDisplay account statusInput recharge informationUpdate balanceDisplay account statusR
41、equest credit expiry dateGet credit expiry dateExpiry dateDisplay expiry dateLog offFigure 2 ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 107 XML Schema data type definition 7.1 DatedTransaction structure This data structure represents a transaction record. Element Name Element Type Optional Description
42、transactionDate xsd:dateTime No The date the transaction occurred. transactionDetails xsd:string No The transaction details. 7.2 Balance structure This data structure represents a balance record. Element Name Element Type Optional Description balanceType xsd:string No Identifies the type of balance.
43、 End user accounts may have one or more balances for different types of usage (e.g Voice, SMS, gaming etc) amount xsd:decimal No Amount of balance 7.3 BalanceExpireDetails structure This data structure represents balance expiry details. Element Name Element Type Optional Description balanceType xsd:
44、string No Identifies the type of balance. End user accounts may have one or more balances for different types of usage (e.g Voice, SMS, gaming etc) date xsd:dateTime Yes It is the date the identified balance will expire. Do not specify if the balance does not expire 8 Web Service interface definitio
45、n 8.1 Interface: AccountManagement The Account Management interface provides access to account information for update and query operations. 8.1.1 Operation: getBalance This message results in getting account balances indicated by the end user identifier and associated end user PIN. The returned amou
46、nt for each balance is specified as a currency amount. End users accounts may have a single balance for all usage, or may have multiple balances for different uses. For example, an end user may have a separate balance for voice calls, SMS messages, and GPRS usage. 8.1.1.1 Input message: getBalanceRe
47、quest Part name Part type Optional Description endUserIdentifier xsd:anyURI No This parameter identifies the end users account. endUserPin xsd:string Yes Contains the end users credentials for authorizing access to the account ETSI ETSI ES 202 391-7 V1.3.1 (2008-05) 118.1.1.2 Output message: getBala
48、nceResponse Part name Part type Optional Description result Balance 1 unbounded No It is a set of Balance records, where each record specifies a balance type and the associated amount. 8.1.1.3 Referenced faults ServiceException from ES 202 391-1 2: SVC0001 - Service error. SVC0002 - Invalid input va
49、lue. SVC0250 - End user authentication failed. PolicyException from ES 202 391-1 2: POL0001 - Policy error. 8.1.2 Operation: getCreditExpiryDate This message results 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 balance will expire. 8.1.2.1 Input message: getCreditExpiryDateRequest Part name Part type Optional Description endUserIdentifier xsd:anyURI No This parameter identifies the end users account. endUserPin xsd:st
