Public Release Note - PayPal Service Connector 5

1 Introduction

Welcome to the Intershop PayPal service connector. The service connector adds PayPal payment methods to your Intershop CM installation.

This release note provides important product information, including version information and dependencies. It also outlines the basic setup and configuration steps.

1.1 References

1.2 Version Information and Dependencies

This delivery and the accompanying documentation are valid for the following combinations of software versions:

Intershop CMPayPal Service ConnectorPayPal Core APIPayPal Merchant SDK
7.8.2.15+5.0.2+1.7.22.15.121
7.9.0.13+5.0.2+1.7.22.15.121
7.10.2.2+5.0.31.7.22.15.121

The PayPal Service Connector 5.0 is based on new Payment API introduced in Intershop Commerce Management 7.6.1.

1.3 Delivery

The package includes the following cartridges:

  • ac_payment_paypal
  • as_responsive_paypal

The table below provides information about the cartridges included in the package. Not all of these cartridges are required.

CartridgeDescriptionRequired
ac_payment_paypalIncludes all base functionality and business logic which is used both in the storefront and the Commerce Management application(tick)
as_responsive_paypal

Enables PayPal payment connector for the following application types:

  • intershop.B2CResponsive
  • intershop.SMBResponsive

The cartridge is optional and may be skipped if the custom project does not support these application types or PayPal is not required in these application types.

(error)

1.4 Supported Application Types

The PayPal Service Connector can be used for the following application types:

Application TypeApplication Type IDDescription
B2C WebShopintershop.B2CResponsiveBusiness to Consumer Channel
SMB WebShopintershop.SMBResponsive

Business to Business Channel

Warning

Applicable only if the order approval is disabled!

2 Setup

This section outlines the basic setup and configuration steps, including

Note

Managing and deploying the PayPal Service Connector requires a continuous integration environment set up and configured as described in Cookbook - Setup CI Infrastructure (valid to Gradle Tools 2.7).

2.1 Precondition

The package is available via Intershop's Public Artifactory.

2.2 Set Up the Assembly

To add the PayPal Service Connector into your Intershop CM system, you may either

  • Incorporate the cartridge into an already existing assembly.
    In the build.gradle file of the assembly add:

    cartridges {
            def paypalPaymentProvider = [
                'ac_payment_paypal', 
                'as_responsive_paypal'
            ]
            include (*(paypalPaymentProvider.collect {"com.intershop.services.payment_paypal:$it:5.0.3"}), in: [development, test, production])    
     
            order = listFromAssembly(baseAssembly) + paypalPaymentProvider
        }
    ...


    For details about adding components to an assembly, see Recipe: Add Cartridges to an Assembly.
    , or

  • Create a new assembly inheriting from a Intershop CM based assembly.
    For details about creating a new assembly, see Recipe: Create a New Assembly Inheriting From an Existing Assembly.

For details about managing assembly artifacts, see:

2.3 Defining File-Based Configuration

Before deploying the new assembly to a test or production environment, you may have to adjust some file-based configurations required by the PayPal Service Connector.

The PayPal Service Connector requires the following settings:

PropertyDescriptionValue
intershop.payment.PAYPAL_STANDARD.currenciesDefines which currencies are configurable for PayPal Standard. Default: EUR,AUD,GBP,DKK,HKD,JPY,CAD,MXN,ILS,NZD,NOK,PLN,SEK,CHF,SGD,CZK,HUF,USDcomma separated list, e.g., EUR, USD
intershop.payment.PAYPAL_EXPRESS.currenciesDefines which currencies are configurable for PayPal Express Default: EUR,AUD,GBP,DKK,HKD,JPY,CAD,MXN,ILS,NZD,NOK,PLN,SEK,CHF,SGD,CZK,HUF,USDcomma separated list, e.g., EUR, USD

According to Recipe: Change Deployed File Content With Filters this setting has to be overridden within <IS_SHARE>/system/config/cartridges/ac_payment_paypal.properties.

For details about adding new configuration files, see Recipe: Deploy Custom Files.

2.4 Deploying Assembly

After creating and appropriately configuring the assembly, you must deploy it to the intended target environment.

For details about deploying an assembly, see Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade).

Note

The PayPal Service Connector requires additional post-deployment configuration steps. For details, refer to Configuration .

3 Customization

3.1 Changing the Definition of Significant Cart Change

The consequent redirects to PayPal (those after the initial redirect) are done after significant cart changes. What is significant in a cart is defined by the class:

com.intershop.adapter.payment.paypal.internal.basket.BasketHashCodeGenerator
@Named("PayPal_BasketHashCodeGenerator")
public class BasketHashCodeGenerator implements Function<BasketBO, String>

It gets the current BasketBO and creates a hash based on what it considers to be significant.

At some stages of the checkout (Payment and Review pages) a hash is generated again and if there is a mismatch with the initial hash, the customer will be redirected to PayPal again.

To change the definition of what is significant in a cart:

  1. Create your own class YourCustomBasketHashCodeGenerator implementing Function<BasketBO, String>, which generates hash based on what you consider significant.
  2. Bind the new class in your customization Guice module.

    bind(new TypeLiteral<Function<BasketBO, String>>()
    {
    }).annotatedWith(BasketHashCodeGenerator.class.getAnnotation(Named.class))
                 .to(YourCustomBasketHashCodeGenerator.class).in(Singleton.class);

4 Configuration

This section outlines the required post-deployment configuration steps, including:

4.1 Adjusting Firewall Settings

Adjust your firewall settings according to PayPal's Go Live Checklist.

4.2 Applying UI Based Configuration

The PayPal Service Connector requires some post-deployment configurations in Organization Management application and Commerce Management application.

For details about enabling a payment service, see - Recipe: Enable a Payment Service.
The table below lists PayPal specific settings you can enter at the payment service.

NameDescription
User NameYour PayPal seller account's username.
PasswordYour PayPal seller account's password.
SignatureYour PayPal seller account's signature.
EnvironmentSwitch between test and live system. Options: live, sandbox and beta-sandbox.
Logo URLThe URL of the logo that will be displayed on the PayPal page after redirect.
Branding IDThe heading that will be displayed on the PayPal page after redirect. Overrides the logo parameter.
Page LayoutThe identifier of the preconfigured page style, that will be used for the PayPal page after redirect. Overrides the logo parameter.
Auto CaptureIf enabled, the amounts will be automatically captured with the authorization.
Allow PayPal address updateIf enabled, the customer can update shipping address via PayPal page.
Allow shipping bucketsEnable PayPal for orders being dispatched to multiple addresses or in multiple shipments.
Digital goodsIf enabled, the customer can buy Digital Gift Certificate.
PayPal Logo URLURL of the PayPal logo, which is shown under PayPal payment methods.
Transfer Order Details

Specifies way to transfer order details to PayPal. Order details include items (prices and quantities), discounts, taxes, handling fees, etc.
See also: Order Detail Transmission Options

PayPal confirmation button typeModifies the text value of the PayPal confirmation button.

4.3 Localization

The PayPal Service Connector provides English and German localization for payment specific input field labels, error messages etc.

You can find the existing localization files here: <IS.INSTANCE.SHARE>/system/cartridges/ac_payment_paypal/release/localizations

For details about localization, see:

5 Feature Overview

5.1 Payment Methods

The PayPal Service Connector adds the following payment methods to your Intershop CM system:

NameDescriptionPayment Management Options

PayPal Standard

Payment via a PayPal account performing the complete authorization/capturing process

Capture, Cancel, Reduce, Refund

PayPal ExpressPayment via a PayPal account using the express checkout button and performing the complete authorization/capturing process

Capture, Cancel, Reduce, Refund

5.2 Payment Management Options

OperationDescription
CaptureRequest for settling the payment, can be submitted via the Intershop Commerce Management or via the PayPal Web interface.
CancelRequest for abandoning (PayPal: voiding) a payment settlement, can be submitted via the Intershop Commerce Management or via the PayPal Web interface.
ReduceOption to lower the capture amount
RefundOption to return (parts of) the capture amount

Note

Capture and Cancel operations performed directly in the PayPal Web interface are not synchronized with Intershop CM. This leads to errors when trying to capture or to cancel those payments in the Intershop Commerce Management.

5.3 Order Detail Transmission Options

The PayPal Connector supports different options transmitting order details to PayPal. To avoid rounding errors it might make sense to adapt this setting within a project in order to make it possible to use PayPal for all use cases.

5.3.1 Explaining Rounding Errors

Rounding errors are related to basket transmission to a payment service provider (PSP). When a PSP provides an API to send the different basket totals with 2-digit values (e.g., shipping, taxes, discounts etc.) a possibility occurs that summing up everything with 5-digit values produces a different result to the total amount for authorization. The difference might be as small as a cent, but still enough for the PSP to reject the payment. The reason for rounding issues is price calculation which includes percentage values. For example:

  • Converting net prices into gross prices.
    This may happen when prices in the Commerce Management application are handled as net and displayed in the storefront as gross.
  • Percentage based discounts

5.3.2 Avoiding Rounding Errors

Since version 4.1 of the PayPal Connector the shop manager has three options to transfer order details (basket transmission) to PayPal.

 

ICM OptionPossible Rounding IssuesExplanationResult at PayPal
No DetailsnoNo details besides the order total appear at PayPal
All Details as Subtotalno

The connector uses parts of the PayPal API.

Order details appear at PayPal as part of the item list.

Details Separatedyes

The connector uses most of the PayPal API.

Order details appear at PayPal at dedicated places.

5.4 Redirecting on Significant Cart Changes

Once the customer is redirected back from PayPal, the contents of the basket are stored as hash. If significant changes are observed before the order is completed, the customer would be redirected again to PayPal to confirm the payment. Such redirects may occur on the payment and review pages of the checkout process.

  • Significant changes are:
    • Product quantity change
    • Adding a product
    • Removing a product
    • Changing the whole or parts of the shipping address:
      • Country
      • City
      • Postal code
      • Address Line 1
  • Significant changes are not:
    • Shipping method change
    • Invoice address changes

Tax Changes

It is possible (although very rarely) that the customer is redirected for a second time to PayPal, which was not influenced by the customer's actions. This may be observed for example if a tax is applied to a product in the ICM storefront, but the tax is later changed due to address change when redirecting back from PayPal. This causes a change of the total amount of the basket, which is considered a significant change and the customer will be redirected again to PayPal to confirm the payment.

6 Limitations

6.1 General Limitations

6.1.1 Matching Price and Taxation Calculation

Please be aware that the PayPal payment cartridge requires a matching price display and tax calculation. That is, the price type and the price display must be either both set to "gross" or both set to "net", and a corresponding taxation service must be enabled.

6.1.2 PayPal Express: Customer Redirect to Payment Page Instead of Review Page

A logged in customer will be redirected to the payment page (not the review page) after confirming payment at PayPal.

However this does not affect the functionality of the cartridge.

6.1.3 Application Types

The payment methods are available for B2C shops and for those B2B shops in which the order approval is disabled.

6.2 Credit Card with IPv6 Addresses

The IP Zones feature requires an IPv4 address on the customer's side. In case the customer has an IPv6 address, the payment method Credit Card will not be displayed on the payment page.

7 Changelog

7.1 Version PAYPAL/5.0.3

  • Bugfix: PAYPAL-153 - Disabled "Allow PayPal address update" feature does not change orginal shipping address anymore.
  • Bugfix: PAYPAL-150 - Fixed NPE.
  • Bugfix: PAYPAL-146 - Fix mapping of first- and lastname when talkover addresses from PayPal account.
  • Bugfix: PAYPAL-139 - Remove wrong error message when customer buys digital goods.

7.2 Version PAYPAL/5.0.2

  • Bugfix: PAYPAL-144 - Ensure compatibility of PayPal Express Checkout with ICM 7.9

7.3 Version PAYPAL/5.0.1

  • New Feature: PAYPAL-115 - Consolidate "Send Address" and "Override Address"
    Based on this feature, version 5.0.1 was created and replaced version 4.2.0 for ICM 7.8

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets