AI OnAI Off

PayPal payment provider - installation and user guide

Table of content

Introduction

This document describes how to install and use the PayPal Payment module for EPiServer Commerce.

Files in the PayPal payment provider project

The following files are included in the project package:

  • Paypal_base.dll (library dll from PayPal.com)
  • PayPalPayment_EN.xml (lang file)
  • CanadianOrUSstates.txt (resource file)
  • ISOCodes.txt (resource file)
  • ConfigurePayment.ascx (and its ascx.cs, ascx.designer.cs file)
  • EditTab.ascx (and its ascx.cs, ascx.designer.cs file)
  • PaymentMethod.ascx (and its ascx.cs, ascx.designer.cs file)
  • PayPal.css
  • PayPal.aspx (and its ascx.cs, ascx.designer.cs file)
  • PayPalRedirect.aspx (and its ascx.cs, ascx.designer.cs file)
  • PayPalPaymentLanding.aspx (and its aspx.cs, aspx.designer.cs file)
  • PayPalPaymentGateway.cs (main payment gateway business)
  • Utilities.cs (contains helper functions)

Deploying the PayPal payment provider files

Downloading the PayPal package will provide you with an EPiServer.Business.Commerce.Payment.PayPal project. Follow these steps to deploy the PayPal Payment Provider to your solution:

  • Deploy PaymentMethod.ascx, PayPal.css, ISOCodes.txt, CanadianOrUSstates.txt to the folder "[~EnotecaSite]\Templates\Enoteca\Units\Placeable\Plugins\Payment\PayPal" of your website. Create the "PayPal" folder if it does not exist, but do not include them in the EPiServer Enoteca Project.
  • Deploy the file ConfigurePayment.ascx to the "[~CommerceManagerFrameworkSite]\Shared\Apps\Order\Payments\Plugins\PayPal". Create the "PayPal" folder if it does not exist (for instance C:\EPiServer\eCommerceFramework\5.3\EnotecaCM\Shared\Apps\Order\Payments\Plugins\PayPal).
  • Deploy the file EditTab.ascx to the "[~CommerceManagerFrameworkSite]\Shared\Apps\Order\Payments\MetaData\PayPal". Create the "PayPal" folder if it does not exist. (for instance  C:\EPiServer\eCommerceFramework\5.3\EnotecaCM\Shared\Apps\Order\Payments\MetaData\PayPal).
  • Deploy the file PayPalPayment_EN.xml to the “lang” folder of the EnotecaSite.
  • Deploy the file PayPal.aspx, PayPalRedirect.aspx, PayPalPaymentLanding.aspx to the folders "[EnotecaSite]/Templates/Enoteca/Pages/", but do not include them in the EPiServer Enoteca Project.
  • The PayPal package includes the following DLLs which are necessary to build the project (Library folder):
    - Mediachase.BusinessFoundation.dll
    - Mediachase.BusinessFoundation.Data.dll
    - Mediachase.Commerce.dll
    - Mediachase.Commerce.Plugins.Payment.dll
    - Mediachase.Commerce.Website.dll
    - Mediachase.DataProvider.dll
    - Mediachase.MetaDataPlus.dll
    - Mediachase.WebConsoleLib.dll
    - paypal_base.dll
  • Rebuild the PayPal project, and you will now have an EPiServer.Business.Commerce.Payment.PayPal.dll.
  • Deploy Paypal_base.dll and EPiServer.Business.Commerce.Payment.PayPal.dll to the "bin" folder of your CommerceManagerSite. (for instance C:\EPiServer\Sites\EnotecaCM\bin).
  • Deploy Paypal_base.dll and EPiServer.Business.Commerce.Payment.PayPal.dll to the "bin" folder of your Enoteca website. (for instance C:\EPiServer\Sites\EnotecaSite\bin).

Handling redirect problem in Chrome/Firefox

For security reasons, Chrome and Firefox (17.0.1 and later) do not allow the redirect of URLs within an iframe, which would prevent the Enoteca sample template from completing checkout with PayPal. To resolve this, you need to add iframe permissions, which can be done as described below.
In <Enoteca Folder>\Templates\Enoteca\Units\Placeable\CheckoutPaymentStep.ascx, change the line number 106 from this:
    <iframe id="paymentMethodsFrame" sandbox="allow-forms allow-same-origin allow-scripts" seamless="seamless" class="enoPaymentMethodFrame" src="" ></iframe>
to the following: 
    <iframe id="paymentMethodsFrame" sandbox="allow-top-navigation allow-forms allow-same-origin allow-scripts" seamless="seamless" class="enoPaymentMethodFrame" src="" ></iframe>>
In <Enoteca Folder>\Templates\Enoteca\Units\Placeable\CompanyPaymentStep.ascx, change the line number 25 from this:
        <iframe id="paymentMethodsFrame" seamless="seamless" class="enoPaymentMethodFrame"  src=""></iframe>>
to the following:
        <iframe id="paymentMethodsFrame" sandbox="allow-top-navigation allow-forms allow-same-origin allow-scripts" seamless="seamless" class="enoPaymentMethodFrame"  src=""></iframe>>

Configuring the IPN service for the Enoteca project

This step is needed in order for the PayPal Payment module to work properly. When the buyer approves the payment with PayPal, the IPN service will update the status of the order. If “Authorization” payment action is selected, the order will change status from “New Order” to “Processing” if authorized properly.

If the payment is under review for risk or has some other pending hold reason from PayPal, it will change status to “Submitted”. If the “Sale” payment action is selected, the order will change to “Shipped” if the payment was successful. Otherwise it will change to “Submitted”. The IPN service uses log4net to log various messages from PayPal for administrators to be able to update the status of an order.

After deploying the project files according to either of the methods above, do the following to set up the IPN service:

  1. Create a page type (for example [Commerce] PaypalLanding) pointing to the PaypalPaymentLanding.aspx template (/Templates/Enoteca/Pages/PayPalPaymentLanding.aspx).
      
  2. Create an EPiServer CMS page from the [Commerce] PaypalLanding page type.
  3. Add a property named PaypalPaymentLandingPage to the Start page page type.
      
  4. Edit the property PaypalPaymentLandingPage on the Start page, and set the page link of the created page to the property's value.
  5. Create a page type (for example [Commerce] PayPal) for the IPN service. This page type points to the PayPal.aspx template which you deployed to your website earlier (/Templates/Enoteca/Pages/PayPal.aspx). This page type does not need any properties.
  6. Create an EPiServer CMS page from the [Commerce] PayPal page type.
  7. Add a property named PayPalPaymentPage to the Start page page type.
  8. Edit the property PayPalPaymentPage on the Start page and set the page link of the created page to the property's value.

Configuring PayPal in Commerce Manager

After deploying all necessary files, open the EPiServer Commerce Manager back-end site and do the following:

  1. Go to Administration/Order System/Payments/English (United States), the last option is the language in which you chose to make the PayPal payment to be available in.
  2. Select Create new payment method. The System keyword option must be “PayPal” (the name of the folder of created during deployment). Class Name must be EPiServer.Business.Commerce.Payment.PayPal.PayPalPaymentGateway.
         

      
  3. When you click OK, the new payment method will be saved with a specific ID.
  4. Open the payment method for editing again, go to the Parameters tab and enter the following:

    - Business email: The main email that you registered with PayPal.
    - API Username: The API user name PayPal will give you when the use registers to use PayPal’s API calls.
    - Password: Your PayPal’s API user password.
    - API Signature: Your PayPal’s API signature.
    - Use test environment (sandbox): Specify here if this is a testing settings or not (sandbox environment or live environment).
    - Allow buyers to change shipping address at PayPal: Defines whether to allow buyers to change their shipping address when reviewing their PayPal payment.
    - Payment action: The payment action buyers will perform at PayPal. Default is Authorization where a payment is authorized only, not yet captured. With the Sale option, the payment will be immediately transferred from buyer’s account to merchant’s account.
    - Allow guest checkout: Allows buyers who doesn’t have a PayPal account to perform a payment. If allowed, buyers will see a billing page from which they can pay using a credit card without having to login to PayPal. If not allowed, the buyer will see a login page when redirected to PayPal.
    - ExpressCheckout URL: The URL to redirect a user to PayPal when the SetExpressCheckout API call is successful. NOTE this URL should change according to the Use test environment option.
    - Skip Order Confirm page: Lets buyers go directly to PayPal after selecting PayPal as payment method. Otherwise buyers will see an order confirmation page before being redirected to the PayPal. By default the buyers will not see the order confirmation page.
    - PayPal Secure Merchant Account ID (PAL) (optional): Used to create the dynamic PayPal mark image on the payment selection page. If nothing is entered here, an API call will be made to PayPal to get it.
     

Configuring the PayPal HashKey (optional)

The communication with PayPal uses a private hash key to ensure security in the communication. This private hash key will be used to create secure hash keys, which appends to an accept URL and a cancel URL. The information about accept URL and cancel URL is sent to PayPal using HTTPS, so these keys will not be exposed.

When PayPal redirects a user to those URLs, the keys are used to verify that the request comes from PayPal only, since only PayPal knows about the keys.

You can configure this hash key in the application settings configuration section under the key “PayPalHashKey”.

Using the PayPal payment provider module

When you have deployed the files and configured the PayPal Payment module on your EPiServer Commerce website, you should have a PayPal option in your checkout procedure:

  1. Select the PayPal payment method on the Payment Options page during check out.
  2. When you click the Continue/Place Order button on the order confirmation page, you will be redirected to PayPal.com to approve the payment.
  3. You can see the shipping and billing addresses entered during the checkout procedure, during which these addresses can be changed.
  4. When you have finalized the approval process, you will be redirected to the “Thank You” (landing) page of the Enoteca site.

NOTE

PayPal.com will check the address (billing and shipping) very carefully. If you use a US address to test, use the correct and complete one with ZIP code, State, and City, otherwise the precheck with PayPal API will fail and you cannot complete the payment. In the Enoteca sample templates, the State is the County field when editing and address (Alaska in the image image).