Computer_Science_Software_Spec

| |Reference |Draft |Page | |[pic] |KIT-V35 |1.24 |1/57 | |[pic] | | | | | |Recipients |Date: | | |Editeurs Internet+ |05/03/2007 | | |Author |Revised |Visa | | |Fabien MOREAU | | | | |Subject | | |Kit v3.5. | | |Author | | |Fabien MOREAU | | |Date | | |19/04/01 | |Document type |General technical description | |Document title |Kit v3.5 w-HA documentation for Internet+ | -/- |Drafts: | |Draft No. |Date: |Author |Action |Reasons | |0.01 |26/10/06 |FM |Created  |Document creation | |1.00 |06/11/06 |FM |Correction |Following KSP comments | |1.10 |23/11/06 |FM |Additions |“Delayed confirmation” and “access control” additions | |1.20 |13/12/06 |FM |Additions |Return to “merchants properties” when canceling (§ 2.3.2.1) | | | | | |+ details regarding « replay » of event notifications (push) (§ 2.3.6.5) | | | | | |+ error codes on “delayed confirmation” (§ 2.4.5) | | | | | |+ error codes on “access control”. (pull) (§ 2.5.5) | |1.21 |05/01/07 |FM |Corrections |Correction of cancellation notification protocol | | | | | |Correction of notification file format (push) | | | | | |Matching operator identifier / responder URL | |1.22 |10/01/07 |FM |Corrections |Correction of error codes for the “delayed confirmation” | |1.23 |26/02/07 |FM |Additions + |Technical pre-requirements: j2sdk1.4.XX (§ 1.1.1.2) | | | | |corrections |+ correction of “KeyProviderParam” parameter (§ 2.3.6.1) | | | | | |+ error code 110 on “responder” servlet (§ 2.3.6.3) | | | | | |+ details on opening a pop-up (§ 3.6) | |1.24 |05/03/07 |FM |Additions |Error codes 100, 101 on “responder” servlet (§ 2.3.6.3) | | | | | | | -/- |Other reference documents: | |Draft No. |Date: |Author |Document name | |Not specified |27/10/06 |C. Roy |Reference Manual for Subscription Packages | CONTENTS Introduction Document aim 1. - Technical pre-requirements for operating Kit v3.5 1.1.1. Hosting platform 1.1.1.1. Operating system 1.1.1.2. Java Virtual Machine 1.1.1.3. SSL protocol management module: “JSSE” 1.1.1.4. Servlet engine 1.1.2. Network considerations 1.1.2.1. During the w-HA application installation 1.1.2.2. In production 1.1.3. Other pre-requisites for integration 1.1.3.1. Decompression Utility program 1.1.3.2. Web Server re-boot 1.1.3.3. System administrator presence 2. Subscription purchases 2.1. Vocabulary: 2.2. Kit v3.5 components - draft dated 13/12/05 (v.1.9) 2.2.1. “Bundle” application “web.xml” configuration file 2.2.1.1. “Bundle” application “web.xml” file structure 2.2.1.2. “Bundle” application Example of “web.xml” file 2.2.2. “pos_bundle” application “productbundle.xml” configuration file 2.2.2.1. “pos_bundle” application “productbundle.xml” file structure 2.2.2.2. “Bundle” application Example of “web.xml” file 2.2.3. “Bundle” application “merchants.xml” configuration file 2.2.3.1. “Bundle” application “web.xml” file structure 2.2.3.2. “Bundle” application Example of “web.xml” file 2.2.4. “pos_bundle” application “Subscription-request.txt” log file 2.2.4.1. “bundle” application (pos_bundle): “subscription-request.txt” file structure 2.2.4.2. “bundle” application (pos_bundle): “subscription-request.txt” file example 2.2.5. “bundle” application (pos_bundle): “Subscription-response.txt” log file 2.2.5.1. “bundle” application (pos_bundle): “subscription-response.txt” file structure 2.2.5.2. “bundle” application (pos_bundle): “subscription-response.txt” file example 2.3. Working principles of the “pos_bundle” servlet for an offer subscription. 2.3.1. OFFER SUBSCRIPTION: “pos_bundle” Servlet 2.3.1.1. “pos_bundle” servlet call 2.3.1.2. “pos_bundle” servlet call example 2.3.1.3. “pos_bundle” servlet call settings 2.3.1.4. Working principles of the “pos_bundle” servlet for an offer subscription. 2.3.1.5. Example of URL created by the “pos_bundle” servlet for a subscription request 2.3.2. SUBSCRIPTION REQUEST REPLY: “pos_bundle” Servlet 2.3.2.1. 1st case: user refuses the subscription: 2.3.2.2. 2nd case: operator refuses the subscription (via the w-HA platform) 2.3.2.3. 3rd case: user subscription acceptance: 2.3.3. SUBSCRIPTION CONFIRMATION 2.3.3.1. Immediate subscription confirmation (autoConfirm=true) : “pos_bundle” Servlet 2.3.3.2. Delayed subscription confirmation (autoConfirm=false): SDK development 2.3.3.3. Delayed subscription confirmation (autoConfirm=false): “pos_requete” Servlet 2.3.4. CONTENT PROVIDER SUBSCRIPTION ACKNOWLEDGEMENT: fulfillmentUrl 2.3.5. CONTENT PROVIDER ACCESS CONTROL 2.3.6. SUBSCRIPTION STATUS CHANGE EVENTS (PUSH) 2.3.6.1. “responder” servlet “web.xml” file structure 2.3.6.2. “responder” servlet Example of “web.xml” file 2.3.6.3. “responder” servlet Receipt of cancellation information 2.3.6.4. “responder” servlet Acknowledgement receipt to the w-HA platform 2.3.6.5. In case the Content Provider pos_responder servlet does not respond: 2.3.6.6. “responder” servlet “notifications.txt” log file writing 2.3.6.7. “responder” servlet “notifications.txt” log file parsing 2.4. Working principles of the “pos_requete” servlet for a delayed subscription confirmation 2.4.1. “pos_requete” servlet call (action=offerConfirm) 2.4.2. “pos_requete” servlet call example (action=offerConfirm) 2.4.3. “pos_requete” servlet call settings (action=offerConfirm) 2.4.4. Using the web interface for delayed confirmation (manual) 2.4.5. w-HA platform response to a delayed confirmation request 2.5. “pos_requete” servlet working principles for access control (“pull” mode). 2.5.1. “pos_requete” servlet call (action=offerConsume) 2.5.2. “pos_requete” servlet call example (action=offerConsume) 2.5.3. “pos_requete” servlet call settings (action=offerConsume) 2.5.4. Using the web interface for access control (manual) 2.5.5. w-HA platform response to an access control request (“pull”) 3. What the merchant must implement to use Kit v3.5: 3.1. Creation of offers and products via the MSCA 3.2. “*.xml” configuration file settings 3.3. SUBSCRIPTION CONFIRMATION 3.4. Using the “responder to receive “push” type info 3.5. Using the “pos_request” servlet (action=offerConsume) for access controls 3.6. Creating offer presentation webpages 3.7. Content protection (using the hmac) 4. ANNEXES: 4.1. Developing a subscription “confirm” via the SDK 4.1.1. Implementation 4.1.2. Code example 4.2. Development of a specific “responder” via the SDK 4.2.1. Implementation 4.2.2. Code example Introduction In order to meet market demand, the Internet+ solution (www.internetplus.fr) has been developed in order to manage not only Event Based payment, but also recurrent subscriptions. Some modifications to the w-HA platform accompany with this development : implementing a new application (v3.5), making a new Web interface available to the Content Providers allowing them to create offers and products (MSCA – Merchant Self Care Application). The Content Provider’s product base, i.e. all of the information (identifier, price, description, purchasing terms, ...) related to these offers and products is therefore present on the w-HA platform, and no longer on the w-HA application (Kit v3.5) installed on his (their) server(s). There is still a product catalogue, limited to one identifier and one delivery URL (ffUrl), on Kit v3.5, to enable linking with the product base. The new w-Ha (Kit 3.5) application installed on the Content Provider server(s) has a certain number of advantages such as: • multi-type payments: Event Based sales and subscriptions • multi-merchants/shops: one single Kit for several merchants or shops Document aim The aim of this document is to describe how the Kit v3.5 works in relation to the w-HA platform and in the Internet+ offer to manage Event Based sale purchases and subscriptions. It is mainly aimed at the w-HA installer on the service Content Provider platform. Another document called “Reference Manual for Subscription Packages” is aimed at shop manager(s). 1) refer to document “Reference Manual for Subscription Packages” 1. Technical pre-requirements for operating Kit v3.5 Implementing the w-HA solution requires the installation of a Java “bundle” application on the merchant’s server. The following diagram illustrates the relationships between the different software and material components necessary for operation the w-HA “bundle” application. [pic] Necessary components for “bundle” application Internaute = internet user Moteur de Servlet = servlet engine Serveur Web = Web server Système d’exploitation = operating system Marchant = merchant The w-HA payment system operation requires installation of the “w-HA” (Java application) application on the service Content Provider hosting platform. 1. Hosting platform The technical environment (operating system and web server) of the Content Provider’s website hosting platform must be compatible with the “w-HA” application. This application relies on the use of Java Servlets enabling compatibility with most platforms on the market. 1. Operating system W-HA guarantees that Kit v3.5 will work properly and ensure technical support for the environments described below. If the operating system is: Sun Solaris version 2.6, version 2.7 or above, w-HA will ensure technical support for the web servers : - Apache Web Server version 1.3.9 or above (with support for DSO modules) If Apache is not installed, install a recent version of 1.3.x or 2.x. Linux Kernel version 2.2.x (glibc/libc6 must be installed) w-HA will ensure technical support for the web servers : - Apache Web Server version 1.3.9 or above (with support for DSO modules) If Apache is not installed, install a recent version of 1.3.x or 2.x. Windows NT version 4.0 (Service Pack 5 or above must be installed) w-HA will ensure technical support for the web servers : - Apache Web Server version 1.3.9 or above (with support for DSO modules) If Apache is not installed, install a recent version of 1.3.x or 2.x. - Internet Information Server version 4.x (IIS4) Windows 2000, w-Ha will ensure technical support for the web servers: - Apache Web Server version 1.3.9 or above (with support for DSO modules) If Apache is not installed, install a recent version of 1.3.x or 2.x. - Internet Information Server version 5.x (IIS5) Windows 2003, w-Ha will ensure technical support for the web servers: - Apache Web Server version 1.3.9 or above (with support for DSO modules) If Apache is not installed, install a recent version of 1.3.x or 2.x. - Internet Information Server version 6.x (IIS6) For other environments (other Operating System / Web Server couples), operating the w-HA application is quite possible, but in this case the installation of Java J2SDK 1.3.x version (or above) and the creation of the “bridge” between the web server and the Servlet engine will be performed by the merchant and will be his sole responsibility. 2. Java Virtual Machine Java 2 SDK version 1.4.x or above must be installed prior to or during the integration. W-HA recommends installing version “j2sdk1.4.x” (for example: j2sdk1.4.2) Note: If the platform is a Linux/UNIX type, the patches required for each component must be installed (for example, when installing j2sdk1.3.x on Solaris 7, the installation document specifies that patches No. xxxxx must be installed). 3. SSL protocol management module: “JSSE” JSSE version 1.0.2 must be installed prior to or during the integration Note: JSSE is included by default in J2SDK Java versions 1.4.x and above. Installation is therefore not necessary. 4. Servlet engine A Servlets/JSP engine complying with the following SUN requirements must be installed prior to or during the integration: - JavaServlet 2.2., - JavaServlets Pages (JSP) 1.1. W-HA recommends the Servlets/JSP engine “Tomcat 4.1.x” (for example: Tomcat 4.1.34). If the Servlets/JSP engine is Tomcat, the Web server must be one of the following: - Apache Web Server version 1.3.9 or above (with support for DSO modules). If Apache is not installed, install a recent version of 1.3.x or 2.x. - Internet Information Server 4 - (IIS4) - Internet Information Server 5 - (IIS5) - For all other Web Servers, or if the merchant’s Servlet engine is not Jakarta-Tomcat operating the w-HA application is quite possible on the condition that the Servlet’s engine complies with the SUN requirements cited above. In this case, integrating the application within the Servlet engine is the merchant’s sole responsibility. W-HA ensures technical support for the w-HA application operation and settings. 2. Network considerations For Kit v.35 to work, some network equipment settings must be considered (port opening, firewalls, proxies) 1. During the w-HA application installation The w-HA application hosting platform must be: - accessible from the outside by the existing Web Server port (by default: port 80) - if possible, accessible from the outside by the Servlet Engine port (by default: port 8080) - Can initiate a SSL communication (on port 443) with the w-HA test platform - The different network equipments (Firewalls, Proxies,…) must therefore be properly configured prior to installation to allow access as mentioned above. 2. In production The w-HA application hosting platform must be: - accessible from the outside by the existing Web Server port (by default: port 80) - Can initiate a SSL communication (on port 443) with the different production platform w-HA nodes with the following URLs (according to the contract signed): https://wanadoo.w-ha.com (Orange internet) https://neufcegetel.w-ha.com (Neuf-Cegetel : not currently available) https://aol.w-ha.com (AOL : not currently available) https://club-internet.w-ha.com (Club-Internet : not currently available) https://tiscali.w-ha.com (Alice : not currently available) https://cb.w-ha.com (Orbéo : not currently available) https://sfr.w-ha.com (SFR Pay : not currently available) The different network equipments (Firewalls, Proxies,…) must therefore be properly configured prior to installation to allow access as mentioned above. 3. Other pre-requisites for integration 1. Decompression Utility program As the Kit v3.5 application is delivered in “zip” or “.tar.gz” form, a decompression utility program such as WinZip, unzip or tar is required. 2. Web Server re-boot Application installation requires a modification of the server(s) configuration (Http server and Servlet Engine). These modifications require a re-boot of the server(s), or even of the machine in some cases. 3. System administrator presence During the application installation and the Web server restart, the hosting platform system administrator’s presence (“root” rights) is required. (1/2 to 1 day approx.) 2. Subscription purchases 1. Vocabulary: In order to fully understand how the w-HA v3.5 platform works, some vital terms must be defined: The product (pId): This is one of the integral components of the offer, specially defined by its delivery URL (ffURL). The offer (oId): This is the subscription model, defining the subscription period and a rate for access to one or more products (only one product for Internet+) The subscription (uoId): This is an aspect of the offer, connected to a user. In summary: An internet user subscribes to an offer (model), he then has a valid subscription. He may then access the products integral to the offer (only one product for Internet+) during the subscription validity period. 2. Kit v3.5 components – draft dated 13/12/05 (v.1.9) Kit v3.5 uses the following components for subscription payments: |“Bundle” application | | |“pos_bundle” Servlet |Manages: | | |- subscription requests on the w-HA platform | | |- subscription request replies | | |- subscription confirmation | |“pos_requete” Servlet |Manages: | | |delayed subscription confirmation | | |access control request (pull) | |“web.xml” configuration file |Contains overall and default settings for Kit v3.5 | |“productbundle.xml” configuration file |Contains the Product Catalogue | |“merchants.xml” configuration file |Contains settings for the different merchant shops | |“Subscription-request.txt” log file |Writes the information regarding subscription requests | |“Subscription-response.txt” log file |Writes the information on subscriptions validated by the w-HA | | |platform | |“Bundle-responder” application | | |“responder” servlet |Manages information receipt from the w-HA platform (“push”) for | | |“cancellation” type events | |“web.xml” configuration file |Mainly contains the shop merchantId | |“notifications.txt” log file |Writes information on “push” type events | |“demo” application | | |/demo/bundle/html/index.html |Enables to check good working order to “pos_bundle” servlet for| | |an offer subscription. | |/demo/bundle/html/requete_confirm_differe.html |Enables to check good working order to “pos_requete” servlet | | |for delayed confirmation subscription request. | |/demo/bundle/html/requete_controle_acces.html |Enables to check good working order to “pos_requete” servlet | | |for access control (“pull” mode). | 1. “Bundle” application: “web.xml” configuration file 1. “Bundle” application “web.xml” file structure |Settings |Comments | |« pos_bundle » | | |Merchant.id |Shop identifier used by default (supplied by w-HA). | | |It enables the w-HA platform to identify the shop. | | |The other settings (key.id, key.value) connected to this shop are present in the file defined by the| | |xmlMarchadDatabase settings. | |Message.url |Access path to JSP that manages the html format error messages (do not modify) | | |The different error cases are sent to the JSP “message.jsp” in the “bundle” application. | |Message.wml.url |Access path to JSP that manages the wml format error messages (do not modify) | | |The different error cases are sent to the JSP “message.jsp” in the “bundle” application. | |Merchant.callback.url |URL where the “pos_bundle” servlet is located on the merchant server (to be modified) | | |URL towards which the user is redirected after accepting the offer subscription on the w-HA payment | | |panel. | | |Adapt with the public IP address or the server public domain name where the “bundle” application is | | |installed. | |Node.paymentPanel.url |URL of the w-HA platform node (supplied by w-HA) | | |The test node URL is: TBA | | |The URL for the production node depends on the operator(s) to which the merchant is connected | | |(Orange, Neuf-Cegetel, AOL, Alice, Club-Internet, Orbeo, …) | |MerchantCurrency |Merchant currenty: EUR (do not modify) | | |The Euro is the only currency accepted on the w-HA platform for Internet+. | | |The Content Provider currency must therefore by set to the EUR value. | | |The offer amount is displayed in Euros on the w-HA payment panel. | |XmlProductDatabase |Access path to the “productbundle.xml” file (do not modify) | | |The “productbundle.xml” file contains the Content Provider’s product catalogue (products and offers)| |XmlMarchandsDatabase |Access path to the “merchant.xml” file (do not modify) | | |The “merchant.xml” contains the settings (key.id, key.value, …) for the different Content Provider | | |shops. | |TimestampDelay |Maximum delay for offer confirmation (in milliseconds, do not modify) | | |Maximum delay between the subscription request and the subscription confirmation | |merchantLogDir |Access path to exceptions log | | |Not currently in use (no log file created for exceptions) | |subRequestFileName |Access path to the subscription-request.txt (do not modify) | | |The “subscription-request.txt” file logs the subscription request information | |subRespondeFileName |Access path to the subscription-response.txt (do not modify) | | |The “subscription-response.txt” file logs the subscription request replies information | |ConsumeFileName |Access path to consume.txt file (not used for Internetplus) | |« pos_requete » | | |Merchant.id |Shop identifier used by default (supplied by w-HA). | | |It enables the w-HA platform to identify the shop. | | |The other settings (key.id, key.value) connected to this shop are present in the file defined by the| | |xmlMarchadDatabase settings. | |Message.url |Access path to JSP that manages the html format error messages (do not modify) | | |The different error cases are sent to the JSP “message.jsp” in the “bundle” application. | |Message.wml.url |Access path to JSP that manages the wml format error messages (do not modify) | | |The different error cases are sent to the JSP “message.jsp” in the “bundle” application. | |Merchant.callback.url |URL where the “pos_requete” servlet is located on the merchant server | | |(NOT USED) | | |Adapt with the public IP address or the server public domain name where the “bundle” application is | | |installed. | |Node.responder.url |URL of the w-HA platform node (supplied by w-HA) | | |URL of the w-HA node on which the “delayed confirmation” request or the “access control” (pull) is | | |made. | | |The URL depends on the operator (Orange, Neuf-Cegetel, AOL, Alice, Club-Internet, Orbeo, ….) where | | |the offer has been subscribed | |XmlMarchandsDatabase |Access path to the “merchant.xml” file (do not modify) | | |The “merchant.xml” contains the settings (key.id, key.value, …) for the different Content Provider | | |shops. | |TimestampDelay |Maximum delay for offer confirmation (in milliseconds, do not modify) | | |Maximum delay between the subscription request and the subscription confirmation | 2. “Bundle” application: Example of “web.xml” file // pos_bundle // MerchantServlet com.wha.core.merchant.simulator.MerchantWhaServlet merchant.id 801 message.url /jsp/message.jsp message.wml.url /jsp/wmlMessage.jsp merchant.callback.url http://wha.marchand.com/bundle/pos_bundle node.paymentPanel.url https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node merchantCurrency EUR xmlProductDatabase /WEB-INF/productbundle.xml xmlMarchandsDatabase /WEB-INF/merchants.xml timestampDelay 300000 merchantLogDir C:\Tomcat4.1\webapps\bundle\WEB-INF\ subRequestFileName C:\Tomcat4.1\webapps\bundle\WEB-INF\subscription-request.txt subResponseFileName C:\Tomcat4.1\webapps\bundle\WEB-INF\subscription-response.txt consumeFileName C:\Tomcat4.1\webapps\bundle\WEB-INF\consume.txt // pos_requete // MerchantConfirmWHAServlet com.wha.core.merchant.simulator.MerchantConfirmWHAServlet merchant.id 801 message.url /jsp/message.jsp message.wml.url /jsp/wmlMessage.jsp merchant.callback.url http://wha.marchand.com/bundle/pos_confirm node.responder.url http://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder xmlMarchandsDatabase /WEB-INF/merchants.xml timestampDelay 300000 MerchantServlet /pos_bundle MerchantConfirmWHAServlet /pos_requete 2. “pos_bundle” application “productbundle.xml” configuration file 1. “pos_bundle” application: “productbundle.xml” file structure |Settings |Comments | |Products | | |ProductId |Product Identifier (as defined in the MSCA) (NOT USED FOR INTERNET+) | | |Unique product identifier used by Kit v3.5 for access control (re-direction or from server to server) | |fulfillmentUrl |Product access URL (NOT USED FOR INTERNET+) | | |(The Content Provider) URL towards which the user is redirected during an access control if his subscription| | |is valid (redirection). | |purchaseCase |Purchase type (NOT USED FOR INTERNET+) | | |Shows the different possible purchase cinematics (Event Based purchase, subscription, consumption) | | |Do not indicate value for Internet+. | |autoConfirm |Automatic access confirmation (NOT USED FOR INTERNET+) | | |- true : the servlet managing access control to the product automatically confirms access then redirects the| | |subscriber to the fulfillementUrl | | |- false : the servlet managing access control to the product redirects the subscriber to the fulfillementUrl| | |The Content Provider has 24 hours to confirm access to the w-HA platform | |Offers | | |offerId |Offer identifier (as defined n the MSCA) | | |Unique offer identifier used by the “pos_bundle” servlet to perform subscription requests (redirection) | |fulfillmentUrl |URL for subscription acknowledgement (to be modified) | | |The Content Provider URL towards which the user is redirected after accepting the offer subscription. | |purchaseCase |Purchase type (NOT USED FOR INTERNET+) | | |Shows the different possible purchase cinematics (Event Based purchase, subscription, consumption) | | |Do not indicate value for Internet+. | |autoConfirm |Automatic access confirmation (by default: true) | | |- true : the “pos_bundle” servlet automatically confirms access then redirects the subscriber to the | | |fulfillementUrl | | |- false : The “pos_bundle” servlet redirects the subscriber to the fulfillmentUrl. | | |The Content Provider has 24 hours to confirm access to the w-HA platform | 2. “Bundle” application: Example of “productbundle.xml” file WEB Merchant Product Database P1 http://www.marchand.com/homepage/acces.php true O1 http://www.marchand.com/abonnement/souscription.php true O2 http://www.marchand.com/abonnement/souscription.php true 3. “Bundle” application: “merchants.xml” configuration file 1. “Bundle” application: “merchants.xml” file structure |Settings |Comments | |mctId |Shop identifier (supplied by w-HA). | |(merchantId) |It enables the w-HA platform to identify the shop. | |mctKeyId |Secret shop key identifier (supplied by w-HA) | |(keyId) |The key identifier is shared between Kit v3.5 and the w-HA platform. | | |It is connected to the “mctKey” and ensures information integrity. | |mctKey |Secret shop key value (supplied by w-HA) | |(keyValue) |The key value is shared between Kit v3.5 and the w-HA platform. | | |It is connected to the “mctKeyId” and ensures information integrity. | |mcttrxCancelFromPaymentPanelUrl |Return URL in case of cancellation from the payment panel | | |If the user clicks on the “Cancel” button on the payment panel, he is redirected to | | |this URL | 2. “Bundle” application: Example of “merchants.xml” file WEB Merchant key Database 801 801 Key for 801 http://www.marchand1.com/abonnement/refus_paiement.php 802 802 Key for 802 http://www.marchand2.com/abonnement/refus_paiement.php 803 803 Key for 803 http://www.marchand3.com/abonnement/refus_paiement.php 4. “bundle” (pos_bundle) application: “Subscription-request.txt” log file The access path to the subscription-request.txt log file is detailed in the Kit v3.5 “web.xml” file. This is the relative path in relating to the “bundle” application. By default: [Tomcat_Home]/webapps/bundle/Web-Inf/subscription-request.txt This is a text file (*.txt) which is updated (a new line is added) each time a new subscription request is performed by the “pos_bundle” servlet. If numerous subscriptions are requested, the file may become as big as several mega octets, causing a an application performance slow-down. Therefore, we recommend implementing rotating logs. 1. “bundle” (pos_bundle) application: “subscription-request.txt” file structure |Fields |Description | |Date |Date of subscription request | |MerchantId |Shop identifier | |KeyId |Secret key identifier | |OfferId (oid) |Offer identifier | |Currency |Offer currency (always EUR for Internetplus) | |Amount |Amount (in Euros) of the subscription | |Promo |Not currently in use | |NodeUrl |Node URL called for the subscription request | |Merchant Propertie #1 |Additional Content Provider setting (#1) | |….. | | |Merchant Propertie #N |Additional Content Provider setting (#N) | 2. “bundle” (pos_bundle) application: “subscription-request.txt” file example Each new subscription request adds a new line containing different fields separated by the “pipe” character (‘|’): 2006-10-10 11:57:57|0|0|CR002|EUR|0.0|promo|https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node|_ap_cur=EUR|_ap_amt=2.44| 2006-10-10 11:59:04|0|0|CR003|EUR|0.0|promo|https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node|_ap_cur=EUR|_ap_amt=2.44| 2006-10-10 11:59:16|0|0|CR003|EUR|0.0|promo|https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node|_ap_cur=EUR|_ap_amt=2.44| 2006-10-10 11:59:31|0|0|CR001|EUR|0.0|promo|https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node|_ap_cur=EUR|_ap_amt=2.44| 2006-10-10 12:02:16|0|0|CR004|EUR|0.0|promo|https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node|_ap_cur=EUR|_ap_amt=2.44| 2006-10-24 16:04:52|0|0|O1|EUR|0.0|promo|https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node|_ap_userId=toto|_ap_sessionId=1234|_ap_cur=EUR|_ap_amt=2.44| 5. “bundle” (pos_bundle) application: “Subscription-response.txt” log file The access path to the subscription-request.txt log file is detailed in the Kit v3.5 “web.xml” file. This is the relative path in relation to the “bundle” application. By default: [Tomcat_Home]/webapps/bundle/Web-Inf/subscription-response.txt This is a text file (*.txt) which is updated (a new line is added) each time a new subscription request is performed by the “pos_bundle” servlet. If numerous subscriptions are requested, the file may become as big as several mega octets, causing a an application performance slow-down. Therefore, we recommend implementing rotating logs. 1. “bundle” (pos_bundle) application: “subscription-response.txt” file structure |Fields |Description | |Date |Date of subscription request | |Status |Subscription status | |MerchantId |Shop identifier | |KeyId |Secret key identifier | |UserOfferId (uoid) |Subscription identifier | |OfferId (oid) |Offer identifier | |Url de Confirm |Url for the w-HA platform to confirm subscription | |Merchant Propertie #1 |Additional Content Provider setting (#1) | |….. | | |Merchant Propertie #N |Additional Content Provider setting (#N) | 2. “bundle” (pos_bundle) application: “subscription-response.txt” file example Each new subscription request adds a new line containing different fields separated by the “pipe” character (‘|’): 2006-10-10 12:33:27|Valid|0|0|U2131792257490213|CR002|https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder|_ap_cur=EUR|_ap_amt=2.44| 2006-10-10 12:34:19|Valid|0|0|U3162266478325413|CR002|https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder|_ap_cur=EUR|_ap_amt=2.44| 2006-10-10 14:26:04|Valid|0|0|U3163266478425413|CR002|https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder|_ap_cur=EUR|_ap_amt=2.44| 3. Working principles of the “pos_bundle” servlet for an offer subscription. For the Internet+ commercial offer, user authentification will be carried out from the service Content Provider website. The user chooses a username and a password and the Content Provider application connects its own username, for example UserId: [pic] 1. OFFER SUBSCRIPTION: servlet “pos_bundle” 1. “pos_bundle” servlet call When the Content Provider wishes to activate a user subscription, he calls on the “pos_bundle” servlet with the “action” setting equal to “authorizeOffer”. This servlet can be called from the Content Provider offer presentation webpage: [pic] Relation Offre Produit = Offer Product relationship Souscription = subscription Offre = Offer Accès au site = Site access 1 semaine = 1 week 1 mois = 1 month 1 trimestre = 1 quarter Produit = Product Accès = access 2. “pos_bundle” servlet call example http://192.168.1.74/bundle/pos_bundle' action=authorizeOffer &oid=O1 &promo=promo &cur=EUR &url=https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node &amt=0.0 &mid=13 &sessionId=1234 &userId=abcd In red : compulsory settings In blue : optional settings 3. “pos_bundle” servlet call settings To activate a subscription, the “pos_bundle” servlet is called with the following settings: Permanent compulsory settings (for Internet+): action=authorizeOffer : to indicate to the servlet that this is a subscription request oid=offer identifier : offer identifier to which the user should subscribe promo=promo : Not currently in use cur=EUR; the currency is the Euro url=Url of the w-HA node (overrun): this setting is used: amt=0.0 : not used by Kit as the offer amount is set by the MSCA When the Content Provider uses the shop defined by default in the « web.xml » file but does not want to use the node by default. For example, by using his Internetplus shop on an operator’s portal and only offering payment to those operator subscribers (noeud operateur.w-ha.com instead of route.w-ha.com) In a compulsory manner if the Content Provider has overrun the mid setting (see below). The node url to use by default is not specified in the “merchants.xml” file, so it must be specified here. Optional settings (for Internet+): mId= shop identifier (overrun) : if the shop to be used is not the one indicated in the “web.xml” file, the Content Provider can indicate which merchantId he wishes to use instead. additional Content Provider settings (or “merchant properties” (mp)): These settings are not compulsory in theory, but in practice the Content Provider uses at least one “Username” setting type which enables him to link one of his customer identifiers (for ex.: userId) with a subscription identifier (uiod) w-HA subscription. The “merchant properties” will be picked up at the subscription acknowledgment Url (fulfillmentUrl) which must be an executable (servlet, cgi, asp, php,…) 4. Working principles of the “pos_bundle” servlet for an offer subscription. When it is called using the setting action=authorizeOffer, the “pos_bundle” servlet performs the following actions: - finds information connected to the shop (merchantId, keyId, keyValue, URLs…) in the “web.xml”. - finds information connected to the offer to be subscribed by the user (OfferId…) in the “productbundle.xml” file. - may find shop settings (merchantId, keyId, keyValue, …) in the “merchants.xml” file if the mid setting has been overrun. - create a secure and signed URL (https) calling the w-HA platform and containing this information as well as the settings (merchant properties) added by the merchant - redirect the internet user to this URL. - updates the “subscription-request.txt” log file 5. Example of URL created by the “pos_bundle” servlet for a subscription request The internet user is redirected to the URL in this form (encoded URL): https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node'm=h%3Dfcd285e561c9f7194 d1c949fd35629cd%3Bp%3D13%3Bk%3D13%3Bv%3D3%3A%7Bc%3DOfferAuthorizeReq%3Bv%3D%7BmUrl%3Dhttp%3A%2F%2F192.168.1.74%2Fbundle%2Fpos_bundle%3Bpromo %3Dpromo%3Boid%3DO1%3Bmp%3D%7Bcur%3DEUR%3BsessionId%3D1234%3BuserId%3Dabcd%3Bamt%3D0.0%3B%7D%3B %7D%7D In decoded URL for clarity: https://qualif1-test-wanadoo.w-ha.com/app-bundlepurchase/node' m=h=fcd285e561c9f7194d1c949fd35629cd5; p=13; k=13; v=3:{ c=OfferAuthorizeReq; v={ mUrl=http://192.168.1.74/bundle/pos_bundle; promo=promo : oid=O1; mp={ cur=EUR; sessionId=1234; userId=abcd; amt =0.00;};}} This URL is secure (https) or not (http) and signed. 2. SUBSCRIPTION REQUEST REPLY: “pos_bundle” Servlet When the user is redirected to the w-HA platform for a subscription request (see previous paragraph), a payment panel is displayed: [pic] (the payment panel may be modified) Votre commande = Your order Produit = Product Service = Service Prix = Price Abonnement Hebdomadaire: offre liberté = Weekly subscription : freedom offer Consultation d’annonces Ile de France = ad search Ile de France Test Abonnement = Subscription test 5 € TTC par semaine = € 5 incl. tax per week Confirmer votre achat = Confirm your purchase Le montant de votre achat sera ajouté à votre prochaine facture Internet Orange = Your purchase amount will be added to your next Orange Internet invoice Vous ne souhaitez pas commander ce service :> annuler la commande = You do not wish to purchase this service : > cancel the order Service acheté aux Conditions de paiement Internet Orange que vous acceptez en confirmant votre achat = Purchasing this service is subject to the Orange Internet payment conditions which you accept by confirming your purchase. The user can either accept the subscription or refuse. 1. 1st case: user refuses the subscription: If the user clicks on the “cancel order” link, the subscription is not validated on the w-HA platform: no subscription identifier is generated True' The user is redirected to the Content Provider “pos_bundle” server (merchant.callback.url) with a “OfferAuthorizeCancel” message. URL example (pos_bundle) to which the user is redirected in case of cancellation from the payment pannel: https%3A%2F%2F192%2E168%2E1%2E74%2Fbundle%2Fpos%5Fbundle%0D%0A%3Fm%3Dh%3D3d476ba31fa0551613a9040251722026%3B%0D%0Ap%3D10%3B%0D%0Ak%3D10%3B%0D%0Av%3D3%3A%7B%0D%0Ac%3DOfferAuthorizationCancel%3B%0D%0Av%3D%7Bmp%3D%7B%0D%0Acur%3DEUR%3B%0D%0Aamt%3D2%2E44%3B%7D%7D In decoded URL for clarity: https://192.168.1.74/bundle/pos_bundle 'm=h=3d476ba31fa0551613a9040251722026; p=10; k=10; v=3:{ c=OfferAuthorizationCancel; v={mp={ cur=EUR; amt=2.44;}} This URL is secure (https) or not (http) and signed. Information included in this URL are: - an hmac to ensure message integrity, - “OfferAuthorizeCancel” message - Additional Content Provider settings (mp) The “pos_bundle” servlet then updated the “subscription-response.txt” log file and redirects the user towards the mcttrxCancelFromPaymentPanelUrl set in the “merchants.xml” file: URL example (mcttrxCancelFromPaymentPanelUrl) to which the user is redirected in case of cancellation from the payment panel: http://192.168.1.74:8080/demo/bundle/html/panel_cancel1.html'hmac%3Dcc4813f17d643b73a6f0cb8d7fe509f6%26amt%3D0.0%26cur%3DEUR%26sessionId%3Dabcd%26userId%3Dtoto In decoded URL for clarity: http://192.168.1.74:8080/demo/bundle/html/panel_cancel1.html 'hmac=cc4813f17d643b73a6f0cb8d7fe509f6 &amt=0.0 &cur=EUR &sessionId=abcd &userId=toto This URL is secure (https) or not (http) and signed. Information included in this URL are: - an hmac to ensure message integrity, - the merchant properties (amt + cur + Content Provider’s own settings) 2. 2nd case: operator refuses the subscription (via the w-HA platform): If the user clicks on the “Confirm your purchase” button, but the subscription cannot be accepted (monthly limit reached, operator invoice payment refused, …) by the w-HA platform, no subscription identifier is created. An error message is displayed for the user, directly on the payment panel. There is not return to the “pos_bundle” servlet to specify the error cause. Consequently, no line is added to the new field “subscription-request.txt” 3. 3rd case: user subscription acceptance: If the user clicks on the “Confirm your purchase” button and the subscription is accepted by the w-HA platform, a subscription identifier is created with an authorized status. The user is redirected to the Content Provider “pos_bundle” server (merchant.callback.url) with a “OfferAuthorizeCancel” message. URL example to which the user is redirected in case of cancellation from the payment panel: https%3A%2F%2F192%2E168%2E1%2E74%2Fbundle3%2Fpos%5Fbundle%3Fm%3Dh%3D3d476ba31fa0551613a9040251722026%3Bp%3D13%3Bk%3D13%3Bv%3D3%3A%7Bc%3DOfferAuthorizationSuccess%3Bv%3D%7Bmp%3D%7Bcur%3DEUR%3BsessionId%3D1234%3BuserId%3Dabcd %3Bamt%3D0%2E0%3B%7D%3Boid%3DO1%3Bru%3Dhttps%3A%2F%2Fqualif1%2Dtest%2Dwanadoo%2Ew%2Dha%2Ecom%2Fapp%2Dnode%2Dmct%2Fresponder%3Bg%5Famt%3D5%3Bz%3D92442%3Bco%3DFR%3Buoid%3D6-U7141248844587211%3Bst%3DFR%3Bci%3DISSY+LES+MOULINEAUX+CEDEX%3B%7D %7D+ In decoded URL for clarity: https://192.168.1.74/bundle/pos_bundle' m=h=3d476ba31fa0551613a9040251722026; p=13; k=13; v=3:{ c=OfferAuthorizationSuccess; v={ mp={ cur=EUR; sessionId=1234; userId=abcd; amt=0.00;}; oid=O1; ru=https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder; g_amt=5; z=92442; co=FR; uoid=6-U7141248844587211; st=FR; ci=ISSY LES MOULINEAUX CEDEX;}} This URL is secure (https) or not (http) and signed. Information included in this URL are: - an hmac to ensure message integrity, - “OfferAuthorizeSuccess” (c=) message, - the subscription amount (g_amt=) - additional Content Provider settings (mp=), - The URL to confirm the subscription (ru=) - the subscription identifier (uoid=) Upon receipt of this request, the “pos_bundle” servlet then updates the “subscription-response.txt” log file. Two cases may then appear regarding this offer depending on the value of the “autoConfirm” setting for the “productbundle.xml” file: * autoConfirm = true If the “autoConfirm” setting of the offer is set at “true”, upon receipt of a “OfferAuthorizeSuccess” message, the “pos_bundle” servlet will automatically and immediately activate the subscription confirmation (see paragraph 2.3.3.1). As for the w-HA, the subscription goes to a “confirmed” status. For the Content Provider, the “pos_bundle” servlet redirects the user to the offer fulfillmentUrl, set in the “productbundle.xml” file. The Content Provider must implement an executable file (CGI, php, jsp, coldfusion,…) for the fulfillmentUrl which will be responsible for acknowledging the subscription. * autoConfirm = false If the “autoConfirm” setting of the offer is set at “false”, upon receipt of a “OfferAuthorizeSuccess” message, the “pos_bundle” servlet will redirect the user to the offer fulfillementUrl set in the “productbundle.xml” file. The Content Provider must implement an executable file (CGI, php, jsp, coldfusion,…) for the fulfillmentUrl which will be responsible for acknowledging the subscription. The Content Provider has 24h hours max (from the offer authorization date) to confirm the subscription (and to make it effective on the w-HA platform) using an SDK supplied the w-HA (see annex I). Beware!! If the Content Provider does not confirm the subscription, it will be valid for the Content Provider, but not for the w-HA thus causing desynchronization of the databases. 3. SUBSCRIPTION CONFIRMATION As opposed to the subscription request and the subscription request reply, which are http(s) redirections, the subscription confirmation is a https request from server to server. It enables to validate the subscription on the w-HA platform: the subscription in question is then granted “confirmed” status. 1. Immediate subscription confirmation (autoConfirm=true) : “pos_bundle” Servlet When the “autoConfirm” setting is set to “true” (see paragraph above), it’s the “pos_bundle” servlet that automatically and immediately creates a “confirm” request to the w-HA platform. Example of subscription confirmation URL, created by the “pos_bundle” servlet: https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder'm=h%3Dfd4685944ae52d91601e343f 7f561d3c%3Bp%3D13%3Bk%3D13%3Bv%3D3%3A%7Bc%3Dm_offerConfirm%3Bv%3D%7Buoid%3D6-U7141248844587211%3B%7D%7D In decoded URL for clarity: https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder' m=h=fd4685944ae52d91601e343f7f561d3c; p=13; k=13; v=3:{ c=m_offerConfirm; v={ uoid=6-U7141248844587211;}} This URL is secure (https) or not (http) and signed. Information included in this URL are: - a hmac to ensure message integrity (h=), - the “m_offerConfirm” (c=) command, - the subscription to be confirmed identifier (uoid=) Upon receipt of this subscription confirmation, the w-HA platform will send back a receipt acknowledgement (ack) to the “pos_bundle” servlet which will then redirect the user to the subscription acknowledgement URL (fulfillmentUrl). 2. Delayed subscription confirmation (autoConfirm=false): SDK development When the “autoConfirm” setting is set to “false”, the “pos_bundle” servlet first redirects the User towards the subscription acknowledgement URL (fulfillment Url) (see paragraph 2.3.4). It is only when the subscription is acknowledged in the Content Provider application (back-office) that it is confirmed on the w-HA platform, within 24 hours max. To this end, w-HA makes available API Java (see Annexes I) which enable to integrate this subscription confirmation request to its own application (back-office) using Java developments. 3. Delayed subscription confirmation (autoConfirm=false): “pos_requete” Servlet See § 2.4 4. CONTENT PROVIDER SUBSCRIPTION ACKNOWLEDGEMENT: fulfillmentUrl When the “pos_bundle” servlet receives a positive subscription request reply form the w-HA platform, it redirects the user to the subscription acknowledgement URL (“fulfillmentUrl”) set in the “productbundle.xml” file. Example of subscription acknowledgement URL created by the “pos_bundle” servlet: http://192.168.1.74/demo/bundle/html/offre1.html'hmac%3D4632bf65f7cedc79ba8a70421a70ca62%26amt%3D2.44%26cur%3DEUR%26uoid%3D6-U7141248844587211%26oid%3DO1%26sessionId%3D1234%26 userId%3Dabcd In decoded URL for clarity: http://192.168.1.74/demo/bundle/html/offre1.html 'hmac=4632bf65f7cedc79ba8a70421a70ca62 &amt=0.0 &cur=EUR &uoid=6-U7141248844587211 &oid=O1 &sessionId=1234 &userId=abcd This URL is secure (https) or not (http) and signed. Information included in this URL are: - a hmac to ensure message integrity (h=), - the subscription identifier (uoid=) - the offer identifier (oid=) - additional Content Provider settings Note: To calculate the hmac, all of the settings must be taken into account including the subscription identifier (uoid). For the subscription acknowledgement URL, the Content Provider must associate the subscription identifier that has just been subscribed (uoid) with the username (ex: userId) in its own application (back-office). [pic] It can then update its database with the subscription identifier (w-HA) by specifying the subscription status (valid or not) and until when (except for a special event, see paragraph 2.3.6). For example: |UserId |UserOfferId |OfferId |ProductId |Validation |Status |Next Charge | |fmoreau12 |6-U7141248844587211 |O1 |P1 |Confirmed |Valid |13/11/2006 16:41 | |msantos012 |6-U8241248844587211 |O2 |P1 |Confirmed |Valid |13/01/2006 17:00 | |fgalle45 |6-U9341248844587211 |O3 |P1 |Authorized |N/A |N/A | |………………… |………. | |P1 |……… | |……………… | |fgalle45 |6-U7141248844588311 |O1 |P1 |Confirmed |Finished |N/A | |fmoreau12 |6-U0441248844587211 |O3 |P1 |Confirmed |Cancelled |20/10/2006 17:31 | 5. CONTENT PROVIDER ACCESS CONTROL As a reminder, in the data model for the w-HA v3.5 platform, the user subscribes to an offer and access a product that is a component of this offer. For the Internetplus offer: - an offer contains only one product (=access to the site or part of the site), - a product can feature in several offers (ex: access to the site for €5/ week, access to the site for €15/month, ….) - access control is only performed by the Content Provider. [pic] To enter the Content Provider website the user identifies himself by using a login/password. This login/password corresponds to a user identifier that belongs to the Content Provider (ex: UserId). The Content Provider must then check in its database if the matching subscription is valid. If the subscription is valid: the Content Provider must enable access to the service If the subscription is invalid: the Content Provider must deny access to the service. 6. SUBSCRIPTION STATUS CHANGE EVENTS (PUSH) Given that access control is performed by the Content Provider for Internetplus offers, communication regarding any event connected to a current subscription (cancellation, refund,…) must be made in real time. The new w-Ha (v3.5) platform includes a “push” mechanism (w-HA to the Content Provider) enabling the Content Provider to immediately update its database with the new subscription status. For the application installed on the Content Provider server, a “responder” servlet (or a similar development around the SDK) is in charge of collecting this information. [pic] Notification de résiliation = cancellation notification Service client opérateur = Operator Customer Service Demande résiliation par email = Cancellation request by email Internaute = Internet User Rubrique « Mon Compte » du FAI = ISP « my account » Section Résiliation = cancellation Identifiant abonnement = subscription identifier Editeur de services = Service Content Provider 1. “responder” servlet: “web.xml” file structure The “responder” servlet has a unique “web.xml” configuration file limited to only a few parameters: |Settings |Comments | |keyProviderParam |Secret shop key value (supplied by w-HA) | | |The key value is shared between Kit v3.5 and the w-HA platform. | | |It is connected to the “mctKeyId” and ensures information integrity. | |logFileName |Access path to the “notifications.txt” file (do not modify) | | |The “notifications.txt” file logs the cancellation notification information | |logExceptionFileName |Access path to the “exceptions.txt” file (do not modify) | | |The “exception.txt” file logs the different exceptions. | 2. “responder” servlet: Example of “web.xml” file keyProviderClassName com.valista.message.SimpleKeyProvider keyProviderParam Key for 505 Responder com.valista.communication.responder.HttpCommunicationResponder NMPOC_NEW com.valista.core.api.merchant.node.impl.VoidNotificationManagerCommand NMIUOAFB com.valista.core.api.merchant.node.impl.VoidNotificationManagerCommand logFileName C:\Tomcat4.1\webapps\bundle-responder\WEB-INF\notifications.txt logExceptionFileName C:\Tomcat4.1\webapps\bundle-responder\WEB-INF\exceptions.txt Responder /responder 3. “responder” servlet: Receipt of cancellation information At the time the cancellation comes into effect: - at the anniversary date for cancellation in the course of a period, - or immediately in the case of a refund, the w-HA platform sends a message to the “responder” servlet of the Content Provider (server to server request). The URL for the “responder” servlet will have been previously communicated to the w-HA. In most cases, the subscription cancellation takes place following a request by the user to his ISP Customer Service Department, but there are other cases listed below: |Code |Comments | |100 |Subscription cancellation via the CSD (ISP Customer Service Department) | | |reason = interrupted connection or incomplete download | |101 |Subscription cancellation via the CSD (ISP Customer Service Department) | | |reason = faulty item | |102 |Cancellation at the end of the subscription validity (license expiration) | |103 |Cancellation connected to subscription invoicing failure | |104 |Cancellation following user account closure by the operator (via the provisionning bus) | |105 |Cancellation following user account closure by the CSD (ISP Customer Service Department tool) | |106 |Cancellation following non-payment of AAR by invoice | |107 |Cancellation due to inability to invoice the user | |110 |Subscription cancellation via the CSD (ISP Customer Service Department) | | |reason = other | The lines highlighted in grey do not apply to Internet+ URL example for a call to a “responder” servlet When a subscription cancellation occurs, the URL called by the w-HA platform is in the following form (encoded URL): http%3A%2F%2Fwha%2Emarchand%2Ecom%2Fbundle%2Dresponder%2Fresponder%3Fm%3Dh%3Df5938cde8dd6bfcb67da921b4b8bf350%3B%0D%0Ap%3D10%3Bk%3D10%3Bv%3D3%3A%7Bc%3DNMPOC%5FNEW%3Bv%3D%7Buo%3D3D6%2DU7141248844587211%3Br%3D103%3Bp%3D%4010%40P1%7C%4010%40P2%7C%4010%40P4%7C%3B%0D%0Ao%3DCR005%3Bc%3DCancelled+due+to+charge+processing+functional+failure%3B%7D%7D%0D%0A In decoded URL for clarity: http://wha.marchand.com/bundle-responder/responder' m= h= f5938cde8dd6bfcb67da921b4b8bf350; p=10 ; k=10 ; v=3 :{ c=NMPOC_NEW; v={ uo=3D6-U7141248844587211; r=103; p=@10@P1|@10@P2|@10@P4|; o=CR005; c=Cancelled due to charge processing functional failure;}} This URL is secure (https) or not (http) and signed. Information included in this URL are: - a hmac to ensure message integrity (h=), - the “NMPOC_NEW” (c=) command - the subscription identifier that has just been cancelled (uo=) - the cancellation code (r=) - the offer affected by the cancellation (o=) 4. “responder” servlet: Acknowledgement receipt to the w-HA platform When the “responder” servlet receives subscription cancellation information, an “acknowledgement receipt” (ack) is sent back to the w-HA platform. The URL for the acknowledgement receipt is in the following form (encoded URL): h%3D492e26bb18d57132c7ea6ce2966fedf5%3Bp%3D10%3Bk%3D10%3Bv%3D3%3A%7Bc%3Dack%3Bv%3D%7Bres%3Dtrue%3B%7D%7D In decoded URL for clarity: h=492e26bb18d57132c7ea6ce2966fedf5; p=10; k=10; v=3:{ c=ack; v={ res=true;}} Important information included in this URL are: - a hmac to ensure message integrity (h=), - a acknowledgement receipt (c=ack), - the result (res=) 5. In case the Content Provider pos_responder servlet does not respond: If the w-HA platform does not receive a cancellation acknowledgement receipt, it will activate new attempts: in total 4 attempts with an hour interval. Furthermore, all the notifications that failed after 4 attempts will be piled and stocked on the w-HA platform: the notifications are buffered while waiting for the next attempt to send. The next attempt occurs after a new notification is successfully sent. In this case, all the awaiting notifications are resent. Please note that the buffered notifications are not automatically unblocked once the Content Provider platform is operational once again. Actually, while the w-HA platform does not receive any new notification requests, the Content Provider platform status will not be tested and the notifications will therefore not be resent. 6. “responder” servlet: “notifications.txt” log file writing The “notifications.txt” file enables to log information entering the “responder” servlet: |Fields |Description | |Date |Cancellation notification receipt date and time | |uo = |the subscription identifier (uoid). | |r = |Cancellation code : see § 2.3.6.3 | |P = |Product list, in the form @@|@@|… | |o = |Offer identifier (oid) | |c = |Description of reason for cancellation | “notification.txt” log file example: Mon Nov 06 19:32:55 2006: uo=6-U4110214534244118; r=103;p=@10@pdt_test2|;o=offre_mscaip2;c=Probleme de debit Mon Nov 06 19:37:54 2006: uo=6-U9181149243591201; r=103;p=@10@pdt_test2|;o=offre_mscaip2;c=Probleme de debit Mon Nov 06 19:42:55 2006: uo=6-U9171712503359101; r=103;p=@10@pdt_test2|;o=offre_mscaip2;c=Probleme de debit Mon Nov 06 19:42:55 2006: uo=6-U5181145243551201; r=103;p=@10@pdt_test2|;o=offre_mscaip2;c=Probleme de debit Mon Nov 06 19:42:55 2006: uo=6-U8110185339521617; r=103;p=@10@pdt_test2|;o=offre_mscaip2;c=Probleme de debit Mon Nov 06 19:42:55 2006: uo=6-U6110216534264118; r=103;p=@10@pdt_test2|;o=offre_mscaip2;c=Probleme de debit 7. “responder” servlet: “notifications.txt” log file parsing In order to take into account the subscription cancellation notifications, the Content Provider must regularly analyze the “notifications.txt” log files to extract the cancelled subscription identifiers and to update the database. 4. Working principles of the “pos_requete” servlet for a delayed subscription confirmation When the “autoconfirm” setting relative to an offer is equal to “false” (recommended by Internet+ to avoid database desynchronizations) in the “productbundle.xml” file, the service Content Provider must “confirm” the w-HA subscription with delay: - either by developing this request from the given API Java (see § 2.3.3.2) - either by using the “pos_requete” servlet included in the application “bundle”. 1. “pos_requete” servlet call (action=offerConfirm) When the internet user subscribes to an offer, it is redirected to the subscription validation URL defined in the “products.xml” file (fulfillmentUrl). When the internet user reaches this URL, this will activate a program (to be developed by a Content Provider in php, java, coldfusion) which will: 1) collect the subscribed package identifiers (uoid), 2) update the Content Provider’s subscription database 3) call the “pos_requete” servlet (action=offerConfirm) to validate the subscription on the w-HA 2. “pos_requete” servlet call example (action=offerConfirm) After updated the subscription database, the Content Provider will call the servlet via his HTTP client (to be developed) by transmitting the necessary settings. In order to do this he will use a URL: http://wha.marchand.com/bundle/pos_requete' action=offerConfirm &mid=10 &uoid=6-U7141248844587211 &url=https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder 3. “pos_requete” servlet call settings (action=offerConfirm) For delayed subscription confirmation, the “pos_bundle” servlet is called with the following settings: action=offerConfirm : to indicate to the servlet that this is a subscription confirmation request mId= shop identifier : shop identifier affected by the “confirmation” request; the keyId values and the matching keyValue are collected by the servlet in the “merchants.xml” file. uoid= the subscription identifier : subscription identifier that has just been subscribed by the internet user and informed in the Content Provider database. url=Url of the w-HA node (responder): the w-HA url node which will receive the subscription confirmation request. The URL node to call depends on the ISP of the subscription. This information is featured in the subscription identifier (first digits): Ex = 6-U7141248844587211 (6 = Orange Internet) The identifier/operator/url matches are given in the table below: |Identifier |Operator |URL (responder) | |6 |Orange Internet |https://wanadoo.w-ha.com/app-node-mct/responder | | | |(only available operator for the pilote phase) | |7 |Alice |https://tiscali.w-ha.com/app-node-mct/responder | |8 |Club-Internet |https://club-internet.w-ha.com/app-node-mct/responder | |10 |AOL |https://aol.w-ha.com/app-node-mct/responder | |25 |Orbeo |https://cb.w-ha.com/app-node-mct/responder | |30 |Neuf-Cegetel |https://neuf.w-ha.com/app-node-mct/responder | 4. Using the web interface for delayed confirmation (manual) A web interface which uses the “pos_requete” servlet (action=offerConfirm) is also available to the Content Provider. It enables the Content Provider: - to properly understand how the servlet works - to perform confirmations manually if necessary. This web interface can be found a the following URL: http://wha.marchand.com/demo/bundle/html/requete_confirm_differe.html : [pic] Requête “confirm” différé de serveur à serveur = Delayed “confirm” request from server to server 5. w-HA platform response to a delayed confirmation request When the offer subscription confirmation (=>subscription) (uoid) is validated the w-HA platform returns the c=ack If an error occurs, the platform returns a specific error code (e=code) based on the following nomenclature: |Code |Wording | |0 |Unknown subscription (uoid): « User offer not found » | |1 |Previously confirmed offer subscription (uoid): « Invalid user offer status ». | | |Generic return code when a subscription (uoid) no longer has an active status | | |(ex: the confirmation is sent after 24 hours from the time of subscribing) | Example: e=1 5. “pos_requete” servlet working principles for access control (“pull” mode). Please note that the Content Provider receives cancellation information from the w-HA (in “push” mode) once these have come into effect (see § 2.3.6). In order to make up for possible “push” system failures (from the Content Provider and/or w-HA), the “pos_requete” server is at the Content Provider’s disposal (action=offerConsume) enabling to check if a subscription is valid (or not) at any given moment. 1. “pos_requete” servlet call (action=offerConsume) The Content Provider must record the next subscription invoicing date in his database (please note, all Internetplus subscriptions have automatic renewal) in order to know the date when the access control request will have to be activated for each Internetplus subscription. The access control request (“pull”) must be performed after the planned subscription renewal date (anniversary) in order to ensure that the subscription has been properly renewed. [pic] Reconduction = renewal Résiliation = cancellation Résiliation effective = effective cancellation 2. “pos_bundle” servlet call example (action=offerConsume) To check that a subscription is still valid, the Content Provider will call the servlet via his HTTP client (to be developed) by transmitting the necessary settings. In order to do this he will use a URL: http://wha.marchand.com/bundle/pos_requete' action=offerConsume &mid=10 &uoid=6-U7141248844587211 &pid=P1 &url=https://qualif1-test-wanadoo.w-ha.com/app-node-mct/responder 3. “pos_requete” servlet call settings (action=offerConsume) To check access (“pull” mode), the “pos_bundle” servlet is called with the following settings: action=offerConsume : to indicate to the servlet that this is a access control request mId= shop identifier : shop identifier affected by the “confirmation” request; the keyId values and the matching keyValue are collected by the servlet in the “merchants.xml” file. uoid= the subscription identifier : subscription identifier connected with a product for which the access control is performed (see diagram § 2.3.5) pid= product identifier: product identifier (in the w-HA sense) which will be subject to access control (see diagram § 2.3.5) url=Url of the w-HA node (responder): the w-HA url node which will receive the subscription confirmation request. The URL node to call depends on the ISP of the subscription. This information is featured in the subscription identifier (first digits): Ex = 6-U7141248844587211 (6 = Orange Internet) 4. Using the web interface for access control (manual) A web interface which uses the “pos_requete” servlet (action=offerConsume) is also available to the Content Provider. It enables the Content Provider: - to properly understand how the servlet works - to perform access controls manually if necessary. This web interface can be found a the following URL: http://wha.marchand.com/demo/bundle/html/requete_controle_acces.html : [pic] Requête “contrôle d’accès” = “access control” request 5. w-HA platform response to an access control request (“pull”) When the product (pid) that is subject to the access control is valid in the user subscription (uoid), the w-HA will return c=ack If an error occurs, the platform returns a specific error code (e=code) based on the following nomenclature: |Code |Wording | |0 |Unknown subscription (uoid): « User offer not found » | |1 |invalid subscription status (uoid): « Invalid user offer status ». | |3 |Unknown product (pid) | |5 |Consumption limit reached for the specified product (pid): « Consume overflow » | |14 |Inactive shop (merchantId) | |15 |The subscription (uoid) does not exist for the specified shop (merchantId) | Example: e=2 3. What the merchant must implement to use Kit v3.5: 1. Creation of offers and products via the MSCA The first stage consists of connecting to the Web interface (MSCA) enabling the Content Provider to create offers and products on the w-HA platform. This web interface can be found a the following URL: https://wanadoo.w-ha.com/app-msca-internetplus/node The username / password is communicated by the w-HA to the Content Provider 2. “*.xml” configuration file settings The Content Provider will have to set the configuration files of the « pos_bundle » servlet web.xml The “web.xml” file should only have to be set once by the Content Provider before going into production. merchants.xml The “merchants.xml” file will be modified by the Content Provider each time a new shop is opened (merchantId) using the Kit v3.5 subscription function. productbundle.xml As for the “productbundle.xml” file, it will be modified by the merchant at each product addition, modification or deletion coherently with the offers and products created on the MSCA. |( |For each modification carried out in the “web.xml” or “products.xml” files (or even “server.xml”), in most cases it is necessary to stop and | | |restart the Servlet engine in order to acknowledge the change!! | 3. Subscription confirmation If the Content Provider decides to manage a delayed supply confirmation (autoConfirm= false) he must: - either develop the “confirm” request to the w-HA platform himself using API Java as supplied by w-HA (see Annex I). - either develop a client http calling the “pos_requete” servlet” (action= offerConfirm) (see § 2.4) 4. Using the “responder to receive “push” type info If the Content Provider decides to use the “responder” servlet, part of Kit v3.5, he must regularly analyze the created log files (notifications.txt) in order to update his subscription database. He will then have to configure the web.xml file for the “responder” servlet. If he would like a more direct integration of his subscription database, he will have to develop his own “responder” using API Java supplied by w-HA (see Annex II). 5. Using the “pos_request” servlet (action=offerConsume) for access controls In order to see if a subscription is valid (or not) at any given moment, the Content Provider must: - develop a client http calling the “pos_requete” servlet” (action= offerConfirm) (see § 2.54) 6. Creating offer presentation web pages The Content Provider will show various subscription offers on his website: [pic] authorizeOffer(O1) authorizeOffer(O2) authorizeOffer(O3) Cette formule offre un accès illimité à = this package offer unlimited access to Mon Site Web = My Website Abonnement hebdomadaire à tacite reconduction, sans engagement de durée, et résiliable à tout moment = Weekly subscription with tacit renewal, no length committement and may be cancelled at any time mensuel = monthly trimestriel = quarterly Suite = Next An example of source code for this is given below: and in the “merchant.js” file the following Javascript: function openPanel(url) { //alert(url); var win = window.open(url, 'valista_PaymentPanel','width=544,height=600,left=10,top=10,status'); } |( | | | |In practice, the merchant carries out “treatments” (for example: writing a sessionId in his database) before calling the | | |“pos_init” servlet to initiate the purchase. | | | | | |Therefore he MUST: | | | | | |1) open the pop-up (when the internet user clicks on the Internet+ button) | | |2) carry out the treatment (the pop-up is already open) | | |2) call the “pos_init” servlet (the pop-up is already open) | | | | | |and NOT: | | | | | |1) carry out the treatment | | |2) open up the pop-up (blocked by anti pop-up mechanisms) | | | | This function deals with displaying the w-HA payment panel in a pop-up of the appropriate size. This is called “valista_PaymentPanel”: The payment panel is displayed: [pic] (the payment panel may be modified) Once the internet user has confirmed his purchase, the w-HA platform closes the “valista-PaymentPanel” window and the customer is redirected to the end page (fulfillmentUrl) for the subscribed offer. This redirection is done in the window that opened the pop-up. 7. Content protection (using the hmac) All information exchanged between the service Content Provider platform and the w-HA will be signed (HMAC-MD5) which will guarantee platform authentification and the integrity of exchanged information. The electronic signature is based on a shared symmetrical crypt encryption key by the merchant platform and that of the w-HA: the mctKey (or KeyValue) Once this information is sent, the “A” platform uses an algorithm to create a MAC (Message Authentification Code) based on the symmetrical key and its information, which will then be transmitted simultaneously to platform “B” in the URL. Upon receipt of this information and the MAC, platform “B” uses the same algorithm to created another MAC based on the same symmetrical key and its information. If it is identical to the one read, no changes to the information has been made: the transaction is authorized. If it is different to the one read, the information has been modified: the transaction is denied. To prevent the Internet User from using a service for free and accessing it directly through its URL (fulfillmentUrl), the following must be checked: - the integrity of additional settings (calculating a HMAC) - the value of one or several additional settings (ex: session identifier) The HMAC is created using a HMAC MD5 algorithm with the following settings: - the settings collected in the fulfillmentUrl (as a unique “string”), - the value of the “mctKey” (or KeyValue) setting for the “merchants.xml” (as a unique “string”), For example, if the return to the end URL (fulfillment Url) is done in the following manner: http://marchand.com/payant/paiement_ok.php'sessionId=1234&commandeId=abcd&userId=toto&hmac=891284e23faa662c033a41dd9905cc10&uoid=U5151292477228013 The program (here “paiement_ok.php”) must check the integrity of settings by calculating the HMAC relative to these settings prior to checking their value and displaying the purchased product/service (or by refusing access if necessary). If the “mctKey” setting value is “a1b2c3d4e5”, then the HMAC calculation id done in the following manner: mon-hmac = H-MAC ("commandeId=abcd&sessionId=1234&uoid=U5151292477228013&userId=toto","a1b2c3d4e5") PLEASE NOTE (1) The additional settings (or “merchant properties” or “mp”) sent to the w-HA servlet must not contain any accents or special characters. The URL encoding of these characters will result in a erroneous HMAC calculation and in this case the product/service delivery will not be carried out even though the end user will be debited. PLEASE NOTE (2) The order of settings for consideration for the HMAC calculation by the w-HA application is an alphabetical order. PLEASE NOTE (3) The subscription identifier (uoide), collected on the fulfillementUrl, must also be taken into account when re-calculating the hmac. A (basic) calculation example for HMAC in PHP: If the fulfillment URL is: http://marchand.com/payant/paiement_ok.php'sessionId=1234&commandeId=abcd&userId=toto&hmac=891284e23faa 662c033a41dd9905cc10&uoid=U5151292477228013 The hmac calculation can be done in the following manner: $hmac_verif = bin2hex (mhash (MHASH_MD5,"commandeId=abcd&sessionId=1234& uoid=U5151292477228013&userId=toto","a1b2c3d4e5f"); if ($hmac_verif == $hmac) print "ok"; else print "no"; 4. ANNEXES: 1. Developing a subscription “confirm” via the SDK If the service Content Provider want to activate the “confirm” (or the “cancel”) of the subscription after ensuring that it has been acknowledged (or not) in the database, he must use the API Java contained in the SDK. A Javadoc (“javadoc.zip” is available to the Content Providers who request it from their w-HA technical support. The service Content Provider must use the following Java classes: - sdk-valista0.jar - CORE-API-1-18-sp0r3-MERCHANT-SDK-lib.jar 1. Implementation Implementation is carried out in the following manner: The Java class for construction must in inherit the following class: Proxy The methods for implementation for confirmation or cancellation are: CancelOffer public void cancelOffer(java.lang.String nodeResponderURL, long merchantId, long keyId, java.lang.String userOfferId) throws com.valista.core.api.node.pos.MerchantOfferManager.CancellationException, java.rmi.RemoteException com.valista.core.api.node.pos.MerchantOfferManager.CancellationException java.rmi.RemoteException ConfirmOffer public void confirmOffer(java.lang.String nodeResponderURL, long merchantId, long keyId, java.lang.String userOfferId) throws com.valista.core.api.node.pos.MerchantOfferManager.ConfirmationException, com.valista.core.api.node.pos.MerchantOfferManager.ReplacementException, java.rmi.RemoteException com.valista.core.api.node.pos.MerchantOfferManager.ConfirmationException com.valista.core.api.node.pos.MerchantOfferManager.ReplacementException java.rmi.RemoteException 2. Code example Proxy proxyValista = new Proxy(keyTable) ; //CancelOffer try { proxyValista.cancelOffer(nodeURL, merchantId, keyId, uoid); forwardToMessageURL(request, response, “CancelSuccess.UserOfferId: “ + uoid); } catch(com.valista.core.api.node.pos.MerchantOfferManager.CancellationException e) { forwardToMessageURL(request, response, “Cancel for” + uoid + “failed” + e.toString()); } //ConfirmOffer try { proxyValista.confirmOffer(nodeURL, merchantId, keyId, uoid); forwardToMessageURL(request, response, “ConfirmSuccess.UserOfferId: “ + uoid); } catch(com.valista.core.api.node.pos.MerchantOfferManager.ConfirmationException e) { forwardToMessageURL(request, response, “Confirm for” + uoid + “failed” + e.toString()); } catch(com.valista.core.api.node.pos.MerchantOfferManager.ReplacementException e) { forwardToMessageURL(request, response, “Replacement Confirmation failed for” + uoid + “failed” + e.toString()); } 2. Development of a specific “responder” via the SDK If the service Content Provider wants to create its own “responder” in order to collect cancellation information and include them directly into his database, he must use the API Java contained in the SDK sdk-valista.jar. A Javadoc (“javadocResponder.zip”) is available to the Content Providers who request it from their w-HA technical support. The service Content Provider must make his Java class inherit the following APIs: - core-api-merchant-sdk-lib.jar - core-util-common.jar 1. Implementation: The implementation is carried out in the following manner: The Java class for construction must in inherit the following class: AbstractNotificationManagerCommand : Type of treated command: NMPOC_NEW: NotificationManagerPushOfferCancellationData(data); The method for implementation for this type of command is: pushOfferCancellation(java.lang.String userOfferId,java.lang.String offerId, com.valista.core.api.merchant.node.NotificationManager.CancelledProductInfo[] products, java.lang.String reasonCode, java.lang.String comment) With the following interfaces: All Implemented Interfaces: com.valista.command.Command, com.valista.util.manager.Manager, com.valista.core.api.merchant.node.NotificationManager, java.rmi.Remote 2. Code example // Referenced classes of package com.valista.core.api.merchant.node.impl : // NotificationManagerPushOfferCancellationData, // Interface à implementer NotificationManager if(cmdType.equals(« NMPOC_NEW »)) { NotificationManagerPushOfferCancellationData data = (NotificationManagerPushOfferCancellationData)cmdData; String reasonCode = data.gerReasonCode(); String comment = data.getComment(); pushOfferCancellation(data.getUserOfferId(),data.getOfferId(),data.getCancelledProducts(), reasonCode, comment); return MessageUtils.createAcknowledgementMessage(null); } Description of the NotificationManager interface: package com.valista.core.api.merchant.node ; import com.valista.util.manager.Manager ; import com.valista.message.ValistaMessageableException ; import java.rmi.RemoteException ; import java.io.Serializable ; public interface NotificationManager extends Manager { public abstract void pushOfferCancellation(String s, String s1, CancelledProductInfo[]cancelledProductInfos, String s2, String s3) throws RemoteException ; } ----------------------- Logo de la Boutique (fourni à w-HA lors de la demande de passage en production) Description de l’offre (MSCA) Conditions financières de l’offre (MSCA) Nom de la Boutique (marque) (à indiquer dans le contrat) valista_PaymenPanel (nom du pop-up)