Don't miss out Virtual Happy Hour this Friday (April 26).

Try our conversational search powered by Generative AI!

AI OnAI Off

PayPal payment provider - installation and user guide

This document describes how to install and use the PayPal payment provider, one of several payment solutions available for EPiServer 7.5 Commerce.

Apps folder

In EPiServer Commerce 7.5, the Apps folder is located in the EPiServer Commerce Manager Shared Files Folder, typically C:\EPiServer\<YourCommerceManagerSite>\eCommerceFramework\5.3\Shared.

If your Commerce Manager site has been updated to the latest version via NuGet, the Apps folder should be located in the wwwroot folder, typically E:\ EPiServer \<YourCommerceManagerSite>\wwwroot\Apps.

Refer to this Apps folder as your corresponding path for the Apps folder mentioned below.

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)
  • PayPalPaymentGateway.cs (main payment gateway business)
  • Utilities.cs (contains helper functions)
  • PayPalPaymentMetaClass.xml (contains payment meta class) 

Deployment

Downloading the PayPal payment provider file package will provide you with an EPiServer.Business.Commerce.Payment.PayPal project. Follow the steps below to deploy the PayPal Payment Provider to your solution.

  1. Deploy PaymentMethod.ascx, PayPal.css, ISOCodes.txt, CanadianOrUSstates.txt to the folder "[~Commerce SampleSite]\Templates\Sample\Units\CartCheckout\PayPal" of your website. Create the "PayPal" folder if it does not exist, but do not include them in the EPiServer Sample Project.
  2. Deploy the file ConfigurePayment.ascx to the Apps\Order\Payments\Plugins\PayPal". Create the "PayPal" folder if it does not exist.
  3. Deploy the file EditTab.ascx to the Apps\Order\Payments\MetaData\PayPal". Create the "PayPal" folder if it does not exist.
  4. Deploy the file PayPalPayment_EN.xml to the “lang” folder of the Commerce Sample site.
  5. Deploy the file PayPal.aspx, to the folders "[Commerce SampleSite]/Templates/Sample/Pages/", but do not include them in the Commerce Sample project.
  6. The PayPal package includes the following DLLs necessary to build the project.
    - EPiServer.dll
    - EPiServer.Framework.dll
    - EPiServer.BaseLibrary.dll
    - EPiServer.Data.dll
    - log4net.dll
    - 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 (included in \PayPal\Lib folder

    Create the "Library" folder directly under EPiServer.Business.Commerce.Payment.PayPal and copy the assemblies (can be found in the bin folder of the front-end and back-end sites) to this.

  7. Add references to those to the PayPal project.
  8. Rebuild the PayPal project, and you will now have an EPiServer.Business.Commerce.Payment.PayPal.dll.
  9. Deploy Paypal_base.dll and EPiServer.Business.Commerce.Payment.PayPal.dll to the "bin" folder of your your CommerceManagerSite. (for instance C:\EPiServer\Sites\CommerceManager\bin).
  10. Deploy Paypal_base.dll, EPiServer.Business.Commerce.Payment.PayPal.dll and Mediachase.WebConsoleLib.dll to the "bin" folder of your Commerce Sample Site. (for instance C:\EPiServer\Sites\Commerce Sample\bin).

Creating PayPal pages

After deploying the project files, follow the steps below to set up a PayPal page.

  1. Create a page type, for example [Commerce] PayPal. This page type will point to the PayPal.aspx template which you deployed to your website earlier (/Templates/Sample/Pages/PayPal.aspx). The page type will not not need to have any properties.
  2. Create an EPiServer CMS page using the [Commerce] PayPal page type.
  3. Add a property named PayPalPaymentPage of the type Page to the Home page page type
  4. Edit the PayPalPaymentPage property on the Home page and set the page link of the created page (in the second step) to the property's value.
        

       

        
  5. Add a property named PaypalPaymentLandingPage of the type Page to the Start page page type.
  6. Edit the PaypalPaymentLandingPage property on the Start page and set the page link of the Home>Self Service>Your Orders to the property's value.

Configuration

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 must be "PayPal" (the name of the folder created during deployment). Class Name must be EPiServer.Business.Commerce.Payment.PayPal.PayPalPaymentGateway, and Payment Class must be EPiServer.Business.Commerce.Payment.PayPal.Orders.PayPalPayment.
         

      
  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 that 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.
       

       
  5. In Commerce Manager, navigate to Administration > Order System > Meta Classes, and click Import MetaData to populate the MetaData import screen. Then select the PayPal\ PayPalPaymentMetaClass.xml file to import.
  6. Finally, go to the Markets tab and add the expected markets for this payment. 

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 PayPal

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 PayPal as payment method on the Payment Options page during check out.
  2. When you click Place Order 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 in the checkout procedure, during which these addresses can be changed.
  4. When you have finalized the approval process, you will be redirected to the “Your Orders” page previously configured.
        

Notification

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.