PayPal Express Application by Kibo eCommerce

Configuration Guide

Current Version: 1.3.1 (April 2016)
Install: Kibo eCommerce App Marketplace
More Info: Version History
Technical Specs & Tests

PayPal is one of the world's largest digital payment processors, serving over 169 million customers in more than 200 markets. The PayPal Express Application by Kibo eCommerce enables you to easily add PayPal's Express Checkout functionality to your existing Kibo eCommerce payment options.

Application Features:

Setup Overview

The following steps are required before you can use PayPal Express Checkout on your site(s):

  1. Install the PayPal Express Application on your tenant.Note: If you create a new site in a tenant after installing the PayPal Express Application, you must reinstall the app to apply the payment configuration settings to the new site.
  2. Update your Kibo eCommerce theme.
  3. Configure PayPal Express in your payment settings.
  4. Enable the app.

Install the App

Kibo eCommerce offers two options for adding PayPal Express Checkout functionality to your tenant:

  1. (Recommended) Contact your Kibo eCommerce sales or professional services representative to install the PayPal Express Application on your tenant.
  2. Build the application from the Kibo eCommerce-provided code on GitHub and install it to Dev Center. This option requires that you have Arc.js enabled on your tenant, and is only recommended if you are working with Kibo eCommerce Professional Services or a Kibo eCommerce Partner and need a highly customized integration. Contact your sales or professional services representative for more information.
Note: If you create a new site in a tenant after installing the PayPal Express Application, you must reinstall the app to apply the payment configuration settings to the new site.

Update Your Kibo eCommerce Theme

Tip: This section assumes you already have a general understanding of how to build, update, install, and apply Kibo eCommerce themes. Refer to the Theme Asset Management topic to learn more about working with themes.

Installing and configuring the PayPal Express app enables PayPal Express functionality in Admin. However, you still must enable PayPal functionality on your storefront so that customers can use it. Kibo eCommerce provides a couple sample themes on GitHub that you can use to integrate PayPal Express functionality:

  1. Select your sample theme:
    • PayPalExpress-Theme—Contains the full source files for the Kibo eCommerce Core 9 theme, with the required changes to enable PayPal Express. Branches of this theme are also available for Core 8, 7, and 6.
    • ThirdpartyPayments-Theme—Contains the full source files for the Kibo eCommerce Core 9 theme, with the required changes to enable both PayPal Express and Pay with Amazon. Use this theme if you are enabling both payment options at the same time. A branch of this theme is also available for Core 8. Note that Pay with Amazon requires the installation of a separate app.
  2. Review and apply the changes made in our sample implementation to your own theme. You can run the git diff command in any command-line shell to see the differences between the sample implementation and your own theme.
  3. Use the Kibo eCommerce Theme Generator or run Grunt to build the theme.
  4. Upload the resulting ZIP file to Dev Center.
  5. Install the updated theme to the sandbox you're working in.
  6. In Admin, go to Main > Site Builder > Themes.
  7. Click the dots next to the new theme and select Apply.

Configure the App

After the PayPal Express application is installed, you must configure your payment settings in Admin to connect Kibo eCommerce with your PayPal account:

Note: If you create a new site in a tenant that already has the PayPal Express Application installed, you must reinstall the app to apply the payment configuration settings to the new site.
  1. In Admin, go to System > Settings > Payments.
  2. Check the PayPalExpress2 checkbox to display the PayPal configuration fields:
    PayPal Express configuration on the Payment and Settings page.
    Note: If you were previously using the built-in PayPal option in Admin (deprecated in the Kibo eCommerce November 2015 Service Update), you must disable that functionality to configure PayPal Express.
  3. Select the PayPal Environment you want to use:
    • Select Sandbox to use PayPal's sandbox environment for testing your PayPal Express integration.
    • Select Production to use a working PayPal environment that processes payments.
  4. Enter the User Name and Password for your PayPal merchant account.
  5. Enter your PayPal API Signature. To find your API signature in PayPal:
    1. Log in to paypal.com with your merchant account.
    2. Click the Profile button.
      PayPal Profile button
    3. On the My Profile page, select My Selling Tools.
      My Selling Tools in PayPal Profile menu
    4. In the Selling online section, locate API access and click Update.
    5. Click View API Signature under NVP/SOAP API integration.
  6. Enter your PayPal Merchant account ID. To find your ID:
    1. Log in to paypal.com with your merchant account.
    2. Click the Profile button.
    3. On the My Profile page, select My Business Info.
    4. Your Merchant account ID appears near the bottom of the list.
  7. Select an Order Processing method:
    • Authorize and Capture on Order Placement both authorizes AND captures payment when an order is placed.
    • Authorize on Order Placement and Capture on Order Shipment authorizes a payment when an order is placed, but does not capture that payment until you manually click the Capture button from the Orders module in Admin. (Typically, you capture payment when you ship an order.)
  8. Click Save to save your PayPal Express settings.

Display Billing Address

You can configure the PayPal Express application to display shoppers' billing address within Admin, on the checkout page, and in confirmation emails.

You can configure this functionality using the Arc.js JSON editor available in Admin. Refer to Getting Started with Arc.js for more information about Arc.js.

To configure the application to display shoppers' billing address:

  1. Make sure you have the latest version of the application installed. The functionality for this feature was added for the May 5, 2016 release.
  2. In Admin, go to System > Arc.js.
  3. Within the paypalProcessor function configuration, set addBillingInfo to true. You can also use the missingLastNameValue to provide a value for the last name in case it is missing from the billing info.
    For example, if you chose to enable adding the billing info from Paypal, the configuration for the paypalProcessor function would look like:
    {
    	"actionId": "http.storefront.routes",
    	"contexts": [
    		{
    			"customFunctions": [
    				{
    					"applicationKey": "a0842dd.mppea.1.2.2.Release",
    					"functionId": "paypalProcessor",
    					"enabled": true,
    					"configuration": {
    						"addBillingInfo": true,
    						"missingLastNameValue": "N/A"
    					},
    					"timeoutMilliseconds": 30000
    				}
    			]
    		}
    	]
    }

Enable the App

After configuration, enable the PayPal Express Application in Kibo eCommerce to apply its functionality to your tenant:

  1. In Admin, go to System > Customization > Applications.
  2. Select the PayPal Express Application.
  3. Click Enable App on the app page.

Use the App

After you have installed the app and merged the theme changes, Check out with PayPal buttons appear on the cart and checkout pages of your Kibo eCommerce site.

Pay with Paypal from the Cart Page

With PayPal Express enabled, your customers see a PayPal button from the Cart page of your site. Complete the following steps to test the user experience:

PayPal Express button on the Cart page
Sample Cart page as it appears to a customer.
  1. Click the Checkout with PayPal button to launch a modal browser window for PayPal.
  2. Create or log in to your PayPal account. Because you are testing the buyer's experience, this should be a different account than your merchant account. You can also choose to remember your account info so you can skip the log-in process for future purchases.
  3. Select your preferred payment method and shipping address from the options saved in your PayPal account. Note: If you have a balance or credit in your PayPal account, PayPal requires you to use all of the balance before it allows you to select a different payment method.
  4. Click Continue to return to the Kibo eCommerce Checkout page. The shipping information from PayPal appears in Kibo eCommerce, and a PayPal logo appears in the Payment Information section.
  5. (Optional) Apply coupons or make changes. You can change any of the information on the Checkout page up until the time you click Place Order. Kibo eCommerce automatically updates PayPal with any changes made through the Checkout page before the order is placed.
  6. Click Place Order. Kibo eCommerce adds any shipping, fees, and taxes to the total charged to your PayPal account, and removes any amount covered by discounts or gift cards.

Pay with PayPal from the Checkout Page

A customer who chooses Proceed To Checkout from the Cart page can still check out with PayPal. Complete the following steps to test the user experience:

  1. On the Checkout page, enter your Shipping Information and select your Shipping Method.
  2. (Optional) Apply any coupons, gift cards, or store credits.
  3. Under Payment Information click the Check out with PayPal button:
    PayPal Express button on the Checkout page
    Sample Checkout page as it appears to a customer.
  4. In the browser window that appears, log in to your PayPal account. Because you are testing the buyer's experience, this should be a different account than your merchant account. Kibo eCommerce automatically sends the shipping address you entered to PayPal, and the full order amount (including shipping, taxes, and discounts) is reflected in the order total.
  5. Select your preferred payment method.
  6. Click Continue to return to the Kibo eCommerce Checkout page.
  7. Click Place Order to complete the order.

Payment Authorization and Capture

Depending on the Order Processing method you chose when you configured the app, when a customer clicks Place Order on a Kibo eCommerce Checkout page, Kibo eCommerce either just authorizes the order or authorizes the order AND captures payment.

Note: Regardless of when you capture payment, Kibo eCommerce strongly recommends you always capture payment from Kibo eCommerce. If you capture payment from your PayPal merchant account, you must then handle any refunds or returns from PayPal, which can throw off your Kibo eCommerce order history.

The order appears in the Orders module in Admin. Note the following details from the Payments tab:

Figure 1: Sample PayPal order as it appears in Kibo eCommerce
Figure 1: A sample PayPal Express order in Kibo eCommerce.
Caption Description
1 The Order Number in Kibo eCommerce matches the Invoice ID in PayPal.
2 The payment Method indicates a payment type of PayPal Express.
3 The Transaction History entry for the payment authorization:
  • 3a - The Transaction ID for the authorization. Transaction IDs always match between Kibo eCommerce and PayPal.
  • 3b - The Response Message for the authorization. This includes the PayPal CorrelationID for the transaction. If you need to contact PayPal Merchant Technical Support about a specific transaction, you can provide this ID to find the transaction.
4 The Transaction History entry for the payment authorization.
  • 4a - The Transaction ID for the payment capture.
  • 4b - The Response Message and PayPal CorrelationID for the payment capture transaction.
Figure 2: Same order as it appears in PayPal
Figure 2: The Transaction Details page for the payment authorization from the same order in PayPal.

Returns

If you return or credit a payment in Kibo eCommerce, the credit appears as a PayPal credit in the customer's PayPal account.

Declines

The PayPal Express Application does not process declines. If you decline a payment in Kibo eCommerce, you must also manually decline the payment in PayPal.