The HTML5 DG Toolkit is released as an experimental alpha. Please file any issues through the Github project.

Express Checkout HTML 5 Local Storage and Inventory Management System

The sample code contained in this project is intended to be used to integrate HTML5 local storage capabilities into an in-context express checkout experience. This project contains several files and directories that are required for integration:

• index.html – Contains a sample integration of the in-context checkout experience.
• pptransact.js – The core front-end code that initiates bill and verify for all products.
• server/[LANGUAGE]/cancel.[EXTENSION] – The page content to display if the user cancels the transaction.
• server/[LANGUAGE]/common.[EXTENSION] – Common functions and variables used by the application. Merchants should replace UID, PASSWORD and SIG values with their our merchant values.
• server/[LANGUAGE]/identity.[EXTENSION] – A series of functions to verify the identity of the user on the merchant’s service. The merchant should replace the content of these functions with their identity verification code.
• server/[LANGUAGE]/inventory.[EXTENSION] – Contains a fetch method for obtaining the inventory of the merchant. Merchants should populate the content of their file with their inventory.
• server/[LANGUAGE]/success.[EXTENSION] – The page content to display if the user completes the transaction.
• server/[LANGUAGE]/pptransact.[EXTENSION] – The server-side functionality for initiating express checkout, verifying purchases and users, and for affecting program flow.

Installation

This example requires the following features to be available on a hosted web server:

• [PHP Installation] – PHP 5.2.x or above.
• [Java Version] – Install Apache Tomcat. Download JSON-lib-jdk Jar file (json-lib-2.2.2-jdk15.jar). Add the tomcat/lib jars and json jar to the project.

Please follow the proceeding steps for integration:

• Download the full source of this example to your web server.
• Load server/[LANGUAGE]/common.[EXTENSION] and replace the entries for UID, PASSWORD, and SIG with your merchant username, password, and signature respectively.
• Load server/[LANGUAGE]/inventory.[EXTENSION] and replace the sample inventory with the inventory of your products. See the below Inventroy File section for more details.
• Load server/[LANGUAGE]/identity.[EXTENSION] and replace the commented sections within each function with hooks to your product’s identity management system. Sample values are provided. See the below Identity File section for more details.
• Insert script source includes and calls to bill and verify showcased in index.html. See the below Include Code section for more details.

Inventory File

Each item to be sold should have its own object within the inventory file. The makeup of an item object is:

array(name => "PRODUCT NAME",
      number => "PRODUCT NUMBER (UNIQUE)",
      qty => "PRODUCT QUANTITY",
      taxamt => "TAX AMOUNT",
      amt => "PURCHASE AMOUNT",
      desc => "PRODUCT DESCRIPTION",
      category => "PRODUCT CATEGORY"
)

[Java Version]
Each item to be sold should have its own object. Its initialized in inventory.jsp file. The makeup of an item object is:

HashMap temp = new HashMap();
temp.put("PRODUCT NUMBER (UNIQUE)", new inventoryItem("PRODUCT NAME", "PRODUCT NUMBER (UNIQUE)", "PRODUCT QUANTITY", "TAX AMOUNT", "PURCHASE AMOUNT",
    "PRODUCT DESCRIPTION", "PRODUCT CATEGORY"));
setInventoryMap(temp);

Implementers should add in a new object entry for each product using this criteria.

Identity File

The identity file contains functions required by the program to verify the identity of the user. The functions within this file need to be updated with hooks to the identity system of the implementing party. The following functions will need to be updated:

verifyUser
Description: Verifies a user by ID
Returns: (boolean) true (valid user) or false (invalid user)
Arguments:

• userId (string): The user id to be verififed

getUserId
Description: Returns the user id for the current user
Returns: (string) The user id
Arguments: None

recordPayment
Description: Saves payment data for a given user
Returns: N/A
Arguments:

• paymentObj (associative array): An object containing all payment data for a given transaction. Data should be saved by the implementer.

verifyPayment
Description: Verifies existing payment stored via recordPayment call.
Returns: (boolean) true (payment verified) or false (payment not verified)
Arguments:

• userId (string): The user id that the purchase was made under.
• itemId (string): The purchased item id.

getPayment
Description: Returns stored payment data
Returns: (associative array) The payment data for a transaction
Arguments:

• userId (string): The user id that the payment was purchased under.
• itemId (string): The item id whose data should be returned for.

Include Code

Within your existing code, insert the following to make requests to the checkout experience:

Include the following script source includes on your page:

<script src="https://www.paypalobjects.com/js/external/dg.js"></script>
<script src="client/jquery-1.6.2.min.js" type="text/javascript"></script>
<script src="client/pptransact.js"></script>

Initialize the pptransact session by adding the language required (first parameter) and whether the toolkit should be target for mobile experiences (second parameter). If the second parameter is true, the user will be redirected for a mobile checkout experience. If false or blank, the flow will be displayed in-context for desktop environments. The following are examples of this:

//INITIALIZE SESSION WITH APPROPRIATE LANGUAGE (php / cf / java)
pptransact.init('py', true); or
pptransact.init('java'); 

Initialize the call to bill for a purchase by doing the following (with replacements where required)

pptransact.bill({
    userId:'[USER ID]',
    itemId:'[ITEM ID]',
    itemQty:'[ITEM QUANTITY]',
    successCallback: function(data){
        //bill success
    },
    failCallback: function(data){
        //bill cancelled 
    }
});

Initialize the call to verify purchase by doing the following (with replacements where required)

pptransact.verify({
    userId:'[USER ID]',
    itemId:'[ITEM ID]',
    successCallback: function(data){
        //verify success
    },
    failCallback: function(data){
        //verify failed 
    }
});

Code Contributions

Copyright 2011 X.commerce

Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.