Broadleaf Microservices
  • v1.0.0-latest-prod

Broadleaf PayPal Integration Release Notes for 3.0.3

New Features & Notable Changes

  • Upgraded PayPal to support new Complete Payment features including the Contact & Shipping Modules

    • Updated PayPal Order payload to include:

      • Venmo Payment Source

      • Order Update Callback Config

      • App Switch Preference

      • Contact Preference

      • Shipping Options

    • Added the BN code as a header to every PayPal API call

    • Added handling of shipping callbacks to the PayPalCheckoutHostedService

    • Added Assertion Header to the create PayPal Order API call

    • Added endpoints to create and fetch orders from PayPal

    • Added a HMAC security token on the callback config to verify the returned shipping callback

Upgrade Notes

Authentication Data

The calls to PayPal create and fetch order have been moved to the backend. To support the new endpoint, new authentication scripts have been added to the environment setup steps. Please review the new data in the environment setup.

Frontend Integration

Review the updated Frontend Integration notes. These contain details around the new supported features.

These features include:

  1. Server-Side Shipping callback configuration

    1. Server-Side Shipping callback integration

    2. PayPal documentation on the Shipping Module

  2. Support for the Contact Module

    1. PayPal documentation on the Contact Module

  3. App Switch Configuration

  4. PayLater Messaging setup

PayPal Frontend Libraries

Additionally, to support the new functionality and backend PayPal v2 endpoint support, changes have been made to the paypal-checkout-js library and a new paypal-checkout-react library has been added.

See paypal-checkout-js and paypal-checkout-react documentation for more details.

Added Configuration Properties

  • broadleaf.paypal-checkout.api.merchant-id

    • Description: The Account ID, also known as the Partner-Merchant-Id or PayPal Merchant ID in the PayPal dashboard. Used when building PayPal Assertion headers.

  • `broadleaf.paypal-checkout.api.populate-shipping-on-order

    • Whether the shipping details should be populated if it’s already known when the PayPal Order is created or updated.

      • Default is false.

      • This should be true if setting the shipping_preference to SET_PROVIDED_ADDRESS in the frontend.

  • `broadleaf.paypal-checkout.api.populate-items-on-order

    • Whether the purchase unit items should be populated if they’re already known when the PayPal Order is created or updated.

      • Default is false.

      • This should be true if setting the shipping_preference to SET_PROVIDED_ADDRESS in the frontend.

  • broadleaf.paypal-checkout.gateway.callback-token-hmac-key

    • The private key used to generate an HMAC token for shipping callback validation.

  • broadleaf.paypal-checkout.gateway.callback-token-hmac-algorithm

    • The algorithm used to generate an HMAC token for shipping callback validation.

    • Default is HmacSHA256.

  • broadleaf.paypal-checkout.gateway.valid-order-callback-statuses

    • The PayPal Order statuses that are valid during shipping callback validation.

    • Default is ["CREATED", "SAVED", "APPROVED", "PAYER_ACTION_REQUIRED"].

  • broadleaf.paypal-checkout.gateway.gateway-reference-for-transaction-id

    • The name of the Payment attribute that the transaction reference ID should be saved as, mapped by transaction type.

    • Default is { AUTHORIZE: "PAYPAL_CUSTOM_ID", AUTHORIZE_AND_CAPTURE: "PAYPAL_CUSTOM_ID" }.

Bug Fixes

  • Updated the Authorize & Capture payment response to include the transactionReferenceId.