Paypal Integration with WCS 7.0

The PayPal flow

Typical order flow for WebSphere Commerce

As shown in Figure 1, a typical order flow for a shopper is:

Checks out from the shopping cart page.
Provides shipping information, chooses a payment option, and provides billing and payment information.
Reviews the order and pays for it.
Receives an order confirmation.

Figure 1. Typical WebSphere Commerce order flow

PayPal order flow with WebSphere Commerce

In an Express Checkout flow, a buyer still checks out at the beginning of the flow. However, after the buyer chooses the PayPal payment method, the buyer is re-directed to the PayPal web site for authentication. After that, the buyer is re-directed back to the WebSphere Commerce store to finish the left order flows. Figure 2 shows the Express Checkout flow.

In the Express Checkout flow, the shopper:

Checks out from the shopping cart page.
Chooses PayPal as the payment method and clicks Next.
Clicks the Checkout with PayPal button.
Logs into PayPal to authenticate his or her identity.
Reviews the transaction on PayPal.
Confirms the order and pays from the site.
Receives an order confirmation.

Figure 2. Order flow with PayPal Express Checkout

Integrating with PayPal Express Checkout

As shown in Figure 3, there are five important steps in the PayPal flow:

When the shopper clicks the Check out with PayPal button, WebSphere Commerce calls the SetExpressCheckout API to retrieve the token and stores this token for later use.
WebSphere Commerce redirects the browser to PayPal with the token initiate shopper approval for the payment.
PayPal redirects back to the RETURNURL (configured in PluginDeployment.xml) of WebSphere Commerce.
PunchoutPaymentCallBackCmd handles the request, retrieves the required parameters used by the Order Summary page, and redirects the shopper to the Order Summary page again. This page hides the Check out with PayPal button and shows the Order button now.
After the shopper clicks the Order button, the WebSphere Commerce Payment framework invokes the approveAndDeposit API of the PayPal plug-in. This invokes the GetExpressCheckoutDetails and DoExpressCheckoutPayment APIs to process the payment.

Figure 3. Detailed order flow with PayPal Express Checkout

Developing a PayPal plug-in

A total of three APIs are used during the shopping flow: SetExpressCheckout, GetExpressCheckoutDetails, and DoExpressCheckoutPayment. These APIs are implemented by the PayPal plug-in. The sample code of the PayPal plug-in is provided with this tutorial. This plug-in has been tested against PayPal's Sandbox.

Download the Payments-Plugin-PayPal.zip file and extract it.
Import it into the toolkit as an existing project. Select File > Import > General > Existing Projects into Workspace as shown in Figure 4.
Figure 4. Import existing projects into the workspace
Switch to the Java EE perspective and add this project to the "WC" project:
1. Double-click the deployment descriptor WebSphereCommerceServer of the "WC" project as shown in Figure 5.
  Figure 5. Add the project into the “WC” project as Module 1
2. In the Design panel, click Application and then click the Add button. Double-click the Module as shown in Figure 6.
  Figure 6. Add the project into the “WC” project as Module 2
3. As shown in Figure 7, select Payments-Plugin-PayPal, click Finish, and then save the change. After Payments-Plugin-PayPal has been added to the “WC” project, publish the Commerce Test Server.
  Figure 7. Add the project into the “WC” project as Module 3

Adding one new payment method for PayPal

Add one new payment policy for PayPal by running the following SQL to create a new payment policy for the store. Choose a number forpolicy_id that is not used by the POLICY table's policy_id column.

insert into policy( policy_id, policyname, policytype_id,storeent_id, properties )
 values( policy_id, 'PayPal', 'Payment', yourMadisonsStoreId,
 'attrPageName=PayPal&paymentConfigurationId=default&display=true&
 compatibleMode=false&uniqueKey=token');
insert into policydesc(policy_id, language_id, Description,longDescription )values
 ( policy_id, languageId, 'PayPal', 'PayPal' );
insert into policycmd (policy_id, businesscmdclass) values (policy_id, 
 'com.ibm.commerce.payment.actions.commands.DoPaymentActionsPolicyCmdImpl') ;
insert into policycmd (policy_id, businesscmdclass) values (policy_id, 
 'com.ibm.commerce.payment.actions.commands.EditPaymentInstructionPolicyCmdImpl') ;
insert into policycmd (policy_id, businesscmdclass) values (policy_id, 
 'com.ibm.commerce.payment.actions.commands.QueryPaymentsInfoPolicyCmdImpl');

For example:

insert into policy( policy_id, policyname, policytype_id,storeent_id, properties )
 values( -44447, 'PayPal', 'Payment', 10101,
 'attrPageName=PayPal&paymentConfigurationId=default&display=true&
 compatibleMode=false&uniqueKey=token');
insert into policydesc(policy_id, language_id, Description,longDescription )values
 ( -44447, -1, 'PayPal', 'PayPal' );
insert into policycmd (policy_id, businesscmdclass) values (-44447, 
 'com.ibm.commerce.payment.actions.commands.DoPaymentActionsPolicyCmdImpl') ;
insert into policycmd (policy_id, businesscmdclass) values (-44447, 
 'com.ibm.commerce.payment.actions.commands.EditPaymentInstructionPolicyCmdImpl') ;
insert into policycmd (policy_id, businesscmdclass) values (-44447, 
 'com.ibm.commerce.payment.actions.commands.QueryPaymentsInfoPolicyCmdImpl');

Develop the payment snippet for this payment method with the PayPal mark inserted as shown by the Shipping/Billing Method page in Figure 3.
Download Sample-files.zip and extract it to a temporary folder and copy PayPal.jsp totoolkitDir/workspace/Stores/YourMedisonsStore/Snippets/EDP/PaymentMethods/. The PayPal mark is added to this page. When the PayPal payment method is selected on the Shipping/Billing Method page, PayPal.jsp is displayed. Change this layout of the sample PayPal.jsp based on your requirement.
Configure the payment for the new payment method. Create the foldertoolkitDir/workspace/WC/xml/config/payments/ppc/plugins/PayPal and put PluginDeployment.xml from the Sample-files.zipfile to this folder.
Configure the action rules. Make a new folder named "PayPal" under the pathtoolkitDir/workspace/WC/xml/config/payments/edp/groups/default/. Copy all the files fromtoolkitDir/workspace/WC/xml/config/payments/edp/groups/default/CreditCardOffline to this folder.

Add the payment mappings from the payment method to the PayPal plug-in:

Add the following code snippet to:

stoolkitDir/workspace/WC/xml/config/payments/edp/groups/default/
 PaymentMappings.xml

Before </PaymentMappings>:

<Mapping paymentMethod="PayPal"
            paymentConfiguration="PayPal"
            paymentActionRule="Early Deposit"/>

Add the following code snippet to:

toolkitDir/workspace/WC/xml/config/payments/edp/groups/default/
 PaymentMethodConfigurations.xml

Before </PaymentMethodConfigurations>:

<PaymentMethodConfiguration 
    name="PayPal"
    paymentSystemName="PayPal" 
    systemEditable="true"
    humanEditable="false"
    refundAllowed="true"
    minimumAmount="0"
    maximumAmount="Unbounded"
    priority="MEDIUM"
    partiallyConsumable="true"
    dependentCreditRequired="true"/>

Add the following code snippet to:

toolkitDir/workspace/WC/xml/config/payments/ppc/plugins/
 PaymentSystemPluginMapping.xml

Before </Mapper>:

<PaymentSystemName name="PayPal" >
 <Mapping paymentConfigurationId="default" pluginName="PayPal"></Mapping>
</PaymentSystemName>

Customizing the Order Summary page

To customize

toolkitDir/workspace/Stores/WebContent/YourMadisonsStore/ShoppingArea/ CheckoutSection/CheckoutPaymentAndBillingAddressSummary.jspf

Add the Checkout with PayPal button to the Order Summary page.
Add the JavaScript action to the Checkout with PayPal button to redirect the page to PunchoutPaymentRedirect.jsp.
Before the token is retrieved from the PayPal, show the Checkout with PayPal button and hide the Order button (first Order Summary page shown in Figure 3). After the token is retrieved from PayPal, hide the Checkout with PayPal button, and show the Order button (second Order Summary page in Figure 3).

Add the Check out with PayPal button to the page:

Open:

toolkitDir/workspace/Stores/WebContent/YourMadisonsStore/ShoppingArea/
CheckoutSection/CheckoutPaymentAndBillingAddressSummary.jspf

Find <c:forEach var="protocolData" items="${paymentInstance.protocolData}">, and add the following code before the corresponding </c:forEach>. This code checks whether there is a PayPal payment method used, and whether the token has been retrieved from PayPal by calling the SetExpressCheckout API, and sets the hasPayPalMethod and sessionInitialized flags for later use.
```
<c:if test="${paymentInstance.paymentMethod.paymentMethodName eq 'PayPal'}">
 <c:set var="hasPayPalMethod" value="true" scope="request"/>
 <c:if test="${protocolData.name eq 'token'}">
  <c:set var="sessionInitialized" value="true" scope="request"/>
 </c:if>
</c:if>
```

Find <c:if test="${order.orderStatus.status eq 'M' and paymentInstance.paymentMethod.paymentMethodName eq 'SimplePunchout', find the corresponding </c:if>, and add the following code snippet behind </c:if>. This code snippet is used to show the “Check out with PayPal” button and defines the JavaScript action for the button. When the button is clicked, the browser is redirected to PunchoutPaymentRedirectView(PunchoutPaymentRedirect.jsp.

<c:if test="${paymentInstance.paymentMethod.paymentMethodName eq 'PayPal' and 
 !sessionInitialized}">
<form id="punchout_${paymentCount.count}" action="PunchoutPaymentRedirectView" 
 method="POST">
 <input type="hidden" name="orderId" value="${order.orderIdentifier.
     uniqueID}" />
 <input type="hidden" name="piId" value="${paymentInstance.uniqueID}" />
 <input type="hidden" name="catalogId" value="${param.catalogId}" />
 <input type="hidden" name="storeId" value="${param.storeId}" />
 <input type="hidden" name="langId" value="${param.langId}" />
</form>
<div id="punchout_${paymentCount.count}_btn" style="display:block;" 
 class="punchout">
<a href="JavaScript:document.getElementById('punchout_${paymentCount.count}').
 submit();" style="color:white;">
 <img src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" 
     align="left" style="margin-right:7px;">
</a>
</div>
</c:if>

To hide the Order button when the "Check out with PayPal" button displays:

Open toolkitDir/workspace/Stores/WebContent/YourMadisonsStore/ShoppingArea/ CheckoutSection/SingleShipment/SingleShipmentSummary.jsp.

Find the following code. The code shows the Order button.

<div class="left" id="WC_SingleShipmentSummary_div_31_2">
  <span class="primary_button button_fit" >
    <span class="button_container">
     <span class="button_bg">
 <span class="button_top">
  <span class="button_bottom">   
    <a id = "singleOrderSummary" href="javascript:setCurrentId
        ('singleOrderSummary');CheckoutHelperJS.checkoutOrder(<c:out value="$
        {order.orderIdentifier.uniqueID}"/
        >,'<c:out value='${userType}'/>','<c:out value='
        ${addressListForMailNotification}'/>')">
     <fmt:message key="ORDER" bundle="${storeText}"/>
      </a>
    </span>
  </span> 
 </span>
      </span>
   </span> 
</div>

Add <c:if test="${!hasPayPalMethod or (hasPayPalMethod and sessionInitialized)}"> before the code, and </c:if>behind the code to let the Order button only display when PayPal is not used, or when PayPal is used and the token has been retrieved.

Customizing PunchoutPaymentCallBackCmd

Copy ExtPunchoutPaymentCallBackCmdImpl.java to package com.ibm.commerce.payment.punchout.commands of the WebSphereCommerceServerExtensionsLogic project.

Run the following SQL statement to register this customized command implementation:

insert into cmdreg values(0,'com.ibm.commerce.payment.punchout.commands.
 PunchoutPaymentCallBackCmd' ,null, 
'com.ibm.commerce.payment.punchout.commands.ExtPunchoutPaymentCallBackCmdImpl',
  null, null, 'Local', null);

Customizing PunchoutPaymentCallBack.jsp

Customize toolkitDir/workspace/Stores/WebContent/PunchoutPaymentCallBack.jsp to redirect the browser to the Order Confirmation page:

Add the following code before the code if ("SimplePunchoutPlugin".equalsIgnoreCase(paymentMethod)) {:

String storeId = (String) request.getAttribute("storeId");
String catalogId = (String) request.getAttribute("catalogId");
String langId = (String) request.getAttribute("langId");
String orderId = (String) request.getAttribute("orderId");
String shipmentTypeId = (String) request.getAttribute("shipmentTypeId");

Add the following else clause following the if clause to redirect the browser to Order Summary page:

else if ("PayPal".equalsIgnoreCase(paymentMethod)){
 response.sendRedirect("http://localhost/webapp/wcs/stores/servlet/
    SingleShipmentOrderSummaryView?catalogId="+catalogId+"&orderId="+orderId+
    "&storeId="+storeId);
}

Registering the action in struts-config-ext.xml

Open toolkitDir/workspace/Stores/WebContent/WEB-INF /struts-config-ext.xml.

Before </global-forwards>, add the following:

<forward className="com.ibm.commerce.struts.ECActionForward" name="PayPal/
 yourMadisonsStoreId" path="/Snippets/EDP/PaymentMethods/PayPal.jsp"/>
 
<forward className="com.ibm.commerce.struts.ECActionForward" 
 name="PunchoutPaymentCallBackView" path="/PunchoutPaymentCallBack.jsp">
 <set-property property="properties" value="storeDir=no"/>
</forward>

Before </action-mappings>, add the following:

<action path="/PayPal" type="com.ibm.commerce.struts.BaseAction"/>

Load the access policy

Copy the file PayPalAccessControlPolicies.xml (inside the Sample-files.zip) to WebSphere/CommerceServer70/xml/policies/xml.
Switch to WebSphere/CommerceServer70/bin and run acpload. For example, for Oracle and Linux environments, the command isacpload.sh orcl wcs wcs1 PayPalAccessControlPolicies.xml.

Registering to PayPal Sandbox accounts

Sandbox is an online payment testing environment provided by PayPal for integration testing. You need to register in Sandbox before you do any testing.

To register to PayPal’s Sandbox:
1. Access the Sandbox using this link: https://developer.paypal.com/cgi-bin/devscr?cmd=_signup-run. Input a real email address. You will receive an email after registering.
2. Activate the account following the email.
3. Logon to PayPal using the registered e-mail and password.
To create a personal account:
1. Go to the Test Accounts page as shown in Figure 8, and click the Preconfigured button.
  Figure 8. Create a test account
2. Select Buyer as the Account Type. Change the password to one that is easy to remember, such as 12345678 as shown in Figure 9.
  Figure 9. Create a test buyer account
To create a business account:
1. On the Test Accounts page, click the Preconfigured button.
2. Select Seller as the Account Type as shown in Figure 10.
  Figure 10. Create a test seller account
3. After the test account has been created, on the API Credentials page as shown in Figure 11, there is detailed information about this account. This includes an API username and password and signature, which are used later.
  Figure 11. API credentials

Configuring the account values as merchant information

Configure the API credentials as merchant information for the store. This information is used by the PayPal plug-in when calling the PayPal APIs.

Create a merchant by logging on to the WebSphere Commerce Accelerator with user wcsadmin. Choose your store to work on. From the same browser, enter the following:
```
https://hostname:8000/webapp/wcs/admin/servlet/PPCMerchantEdit?actionName=
 create&merchantName=myMerchant
```
This URL creates a merchant named myMerchant. Note that the browser window returns a blank page. Check whether a new row with this NAME value has been inserted with the following SQL:
```
SELECT * FROM MERCHANT WHERE NAME='myMerchant';
```
Note the value of MERCHANT_ID for future use.
Associate the merchant with the store. Using the same browser, enter the following URL and replace MERCHANT_ID with the one from the previous step:
```
https://hostname:8000/webapp/wcs/admin/servlet/PPCStoreMerchantAssociate?actionName=
 create&merchantId=MERCHANT_ID
```
This URL creates an association with the Madisons store. Note that the browser window returns a blank page. Check whether a new row with this MERCHANT_ID value has been created by the following SQL:
```
SELECT * FROM STOREMERCH WHERE MERCHANT_ID=MERCHANT_ID;
```
Create a merchant configuration. Using the same browser window, enter the following URL and replace MERCHANT_ID with the one from the previous step:
```
https://hostname:8000/webapp/wcs/admin/servlet/PPCMerchantConfigurationEdit?
 actionName=create&merchantId=MERCHANT_ID&
 paymentConfigurationGroup=default&paymentSystemName=PayPal
```
This URL creates a merchant configuration. Note that the browser window returns a blank page. Check whether a new row with this MERCHANT_ID value has been inserted with the following SQL:
```
SELECT * FROM MERCHCONF WHERE MERCHANT_ID=MERCHANT_ID;
```
Note the value of MERCHCONF_ID for future use.

Create the merchant configuration information. Using the same browser window, enter the following URLs and replace MERCHCONF_ID with the one noted from the last step:

https://hostname:8000/webapp/wcs/admin/servlet/PPCMerchantConfigurationInfoEdit?
 actionName=create&merchantConfId=MERCHANT_ID&propertyName_1=USER
 &propertyValue_1=ValueOfUser&propertyName_2=PWD&propertyValue_2=
 ValueOfPassword&propertyName_3=SIGNATURE&propertyValue_3=
 ValueOfSignature

The values for the USER, PWD, and SIGNATURE are the API Username, API Password, and Signature shown on the API credentials page after the business account has been created. For example:

https://localhost:8000/webapp/wcs/admin/servlet/PPCMerchantConfigurationInfoEdit?
 actionName=create&merchantConfId=10001&propertyName_1=USER&propertyValue_1=
 song_2_1292209255_biz_api1.sohu.com&propertyName_2=PWD&propertyValue_2=1292209264
 &propertyName_3=SIGNATURE&propertyValue_3=AnuqAWRi7my4.
 hv1OR-5hrTorkajAQyLbDhjfZO0f4m2kvS6Y9O45Fur

This URL creates a set of merchant configuration entries that stores the PayPal account information. Note that the browser window returns a blank page. Check whether three new rows with this MERCHCONF_ID value have been inserted with the following SQL:

SELECT * FROM MERCHCONFINFO WHERE MERCHCONF_ID=MERCHCONF_ID;

The values are encrypted.

Importing PayPal’s digital certificate

Get the certificate from PayPal:
1. View https://api-3t.sandbox.paypal.com/nvp, right-click the page, and click Certificates.
2. On the Certificate window (Figure 12), switch to the Details tab, and click Copy to File.
  Figure 12. Export certificate
3. When the certificate Export Wizard pops up, click Next.
4. Select DER encoded binary X.509(.CER) and click Next.
5. Browse to a location to store the certificate and click Next.
Import the digital certificate:
1. Execute ikeyman.bat in the path toolkitDir/wasprofile/bin/.
2. Click the Open icon (Figure 13) and choose PKCS12 as the Key database type.
3. Click Browse, choose the trust.p12 file under the path toolkitDir/wasprofile/config/cells/localhost/nodes/localhost/, and then click OK.
  Figure 13. Import certificate 1
4. Enter WebAS as the password in the password window and click OK.
5. Select Signer Certificates (Figure 14) and click the Add button.
6. Browse for the certificate file you have exported previously and click OK.
  Figure 14. Import certificate 2
7. Enter a label for the certificate as shown in Figure 15 and click OK.
  Figure 15. Import certificate 3
8. As shown in Figure 16, the certificate has been successfully imported to the key database.
  Figure 16. Import certificate 4

Testing the integration

Re-publish the WebSphere Commerce server.
Add one product to the shopping cart.
Choose PayPal as the payment method.
On the Order summary page, click Check out with PayPal.
The browser is redirected to PayPal. On the PayPal page, log in with your personal account's log-in e-mail and password similar to the one shown in Figure 17.
Figure 17. Logon to PayPal with a personal account
Click Continue on the next page. The browser is redirected back to the Order Summary page of WebSphere Commerce.
On the Order Summary page, click the Order button. The order is successfully processed.

Deploying to a production environment

You have completed the previous steps in a toolkit environment for the convenience of development and unit testing. You can now deploy to a WebSphere Commerce production environment.

Follow the same steps as above, but consider the following points that are different from completing the steps in the toolkit environment:

When deploying the Payments-Plugin-PayPal project in the toolkit, you need to import and add the project to the WebSphere Commerce modules. For the runtime environment, you need to package the Payments-Plugin-PayPal project from the toolkit to a JAR file (see Packaging Java EE assets for an entire module in the Information Center), and then deploy it to the WebSphere Commerce server as an EJB (seeDeploying J2EE assets for an entire module in the Information Center).
For the Importing PayPal’s digital certificate section, you need to export and import the certificate using the real PayPal express check out URL (https://www.paypal.com) instead of the Sandbox's URL.
Register a real PayPal account instead of a Sandbox testing account if you want to use the PayPal payment method for online stores. Then configure the USER, PWD, and SIGNATURE of the real PayPal business account as the merchant configuration information.

Remember to change the following parameters in PluginDeployment.xml, according to the host name of the WebSphere Commerce server and the real PayPal express check out URL. Refer to the PayPal Checkout Integration Guide on how to request the account.

<PluginProperty name="initializationBaseURL" value="https://api-3t.sandbox.
 paypal.com/nvp" />
<PluginProperty name="authenticationBaseURL" value=
 "https://www.sandbox.paypal.com/cgi-bin/webscr" />
<PluginProperty name="RETURNURL" value="http://localhost/webapp/wcs/stores/
 servlet/PunchoutPaymentCallBack" />
<PluginProperty name="CANCELURL" value="http://localhost/webapp/wcs/stores/ 
  servlet/PunchoutPaymentCallBack" />

For ExtPunchoutPaymentCallBackCmdImpl.java, put the class file in the same package as the runtime's WebSphereCommerceServerExtensionsLogic.jar as a patch.

IBM WCS - IBM WEBSPHERE COMMERCE