PayPal Environment Setup

Prerequisites for Development/Staging Environments

To use the BroadleafCommerce PayPal payment functionality in a test environment, you must establish sandbox accounts with PayPal.

Add the Maven Dependency

Once you have established an account with PayPal, begin by including the PayPal module dependency to your PaymentTransactionServices project.

<dependency>
    <groupId>com.broadleafcommerce.microservices</groupId>
    <artifactId>broadleaf-micro-paypal</artifactId>
</dependency>

Note	The dependency’s version will be pulled from the Broadleaf release train `pom.xml`.

Configuring the Integration

Configuration for PaymentTransactionServices & This Module

Required Properties

broadleaf.paypal-checkout.api.environment
- Description: Declares whether production or non-production/test transactions should be executed.
- Available values: SANDBOX, PRODUCTION
- Default value: SANDBOX
broadleaf.paypal-checkout.api.client-id
- Description: The client id provided by PayPal that is used in API calls to identify the charging company/entity.
broadleaf.paypal-checkout.api.client-secret
- Description: The client secret provided by PayPal that is used in API calls to verify the application’s usage of the client id.
broadleaf.paypal-checkout.api.payment-description
- Description: A simple description of the entity that is charging the customer.
- Example value: My Test Store
broadleaf.paypal-checkout.api.oauth2-client-token-url
- Description: The URL to use when fetching an oauth2 token for PayPal.
- Example value: https://api-m.sandbox.paypal.com/v1/oauth2/token
broadleaf.paypal-checkout.api.provider.api-url
- Description: The base URL for PayPal V2 APIs.
- Example value: https://api-m.sandbox.paypal.com

Note
client-id, client-secret, payment-description, and oauth2-client-token-url are discriminated properties, meaning that they can be defined for each application or tenant. For example, the client-id can be defined globally via broadleaf.paypal-checkout.api.client-id, for a specific tenant via broadleaf.paypal-checkout.api.tenant.{your_tenant_id}.client-id, or for a specific application via broadleaf.paypal-checkout.api.application.{your_application_id}.client-id.

Optional Properties

broadleaf.paypal-checkout.api.payment-decline-codes
- Description: The list of transaction failure codes that should be considered a form of payment decline when a 400 response code is returned from the PayPal API.
- Example value: INSTRUMENT_DECLINED or INSUFFICIENT_FUNDS
broadleaf.paypal-checkout.api.invalid-payment-method-decline-codes
- Description: The list of transaction failure codes that should be considered a form of payment method decline when a 400 response code is returned from the PayPal API.
- Example value: CREDIT_CARD_CVV_CHECK_FAILED or PAYMENT_METHOD_UNUSABLE
broadleaf.paypal-checkout.api.provider.retrieve-order-details-uri
- Description: The URI to read the order details.
- Default value: /v2/checkout/orders/{id}
broadleaf.paypal-checkout.api.provider.create-order-uri
- Description: The URI to create the payment order.
- Default value: /v2/checkout/orders
broadleaf.paypal-checkout.api.provider.update-order-uri
- Description: The URI to update the payment order.
- Default value: /v2/checkout/orders/{id}
broadleaf.paypal-checkout.api.provider.authorize-payment-for-order-uri
- Description: The URI to authorize the payment for an order.
- Default value: /v2/checkout/orders/{id}/authorize
broadleaf.paypal-checkout.api.provider.capture-payment-for-order-uri
- Description: The URI to capture the payment for an order.
- Default value: /v2/checkout/orders/{id}/capture
broadleaf.paypal-checkout.api.provider.retrieve-authorized-payment-details-uri
- Description: The URI to retrieve the details for an authorized payment by ID.
- Default value: /v2/payments/authorizations/{authorization_id}
broadleaf.paypal-checkout.api.provider.capture-authorized-payment-uri
- Description: The URI to capture an authorized payment by ID.
- Default value: /v2/payments/authorizations/{authorization_id}/capture
broadleaf.paypal-checkout.api.provider.void-authorized-payment-uri
- Description: The URI to void, or cancel, an authorized payment by ID.
- Default value: /v2/payments/authorizations/{authorization_id}/void
broadleaf.paypal-checkout.api.provider.refund-captured-payment-uri
- Description: The URI to refund a captured payment by ID.
- Default value: /v2/payments/captures/{capture_id}/refund

Configuration for CartOperationServices

The following properties should be added to the CartOperationServices configuration, so that this module is included as an available payment method in responses from the checkout payment method options endpoint.

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-payment-method-options:
          - payment-method-type: THIRD_PARTY_ACCOUNT
            payment-method-gateway-type: PAYPAL_CHECKOUT_V2

PAYPAL_CHECKOUT_V2 should be added to the following property to declare when transactions for this gateway should be executed, relative to other gateways, during checkout processing.

broadleaf:
  cartoperation:
    service:
      checkout:
        payment-gateway-priorities:
          - ...
          - PAYPAL_CHECKOUT_V2
          - ...

By default, Authorize transactions are executed by CartOps during checkout. If you wish to execute AuthorizeAndCapture transactions instead, define the following property:

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-transaction-types:
          PAYPAL_CHECKOUT_V2: AUTHORIZE_AND_CAPTURE

Note

This property is application-discriminated, allowing different values to be provided on a per-tenant or per-application basis using the following property paths:

broadleaf.cartoperation.service.checkout.tenant.mytenant.checkout-transaction-types.PAYPAL_CHECKOUT_V2=AUTHORIZE_AND_CAPTURE
broadleaf.cartoperation.service.checkout.application.myapplication.checkout-transaction-types.PAYPAL_CHECKOUT_V2=AUTHORIZE_AND_CAPTURE

"mytenant" & "myapplication" being the Broadleaf Tenant and Application ids.

Configuration for OrderOperationServices

PAYPAL_CHECKOUT_V2 should be added to the following property to declare when ReverseAuthorize or Refund transactions for this gateway should be executed, relative to other gateways, when cancelling a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        cancel-payment-gateway-priorities:
          - ...
          - PAYPAL_CHECKOUT_V2
          - ...

PAYPAL_CHECKOUT_V2 should be added to the following property to declare when Capture transactions for this gateway should be executed, relative to other gateways, when capturing payment for a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        capture-payment-gateway-priorities:
          - ...
          - PAYPAL_CHECKOUT_V2
          - ...

PAYPAL_CHECKOUT_V2 should be added to the following property to declare when Refund transactions for this gateway should be executed, relative to other gateways, when refunding payment for a fulfillment return.

broadleaf:
  orderoperation:
    service:
      payment:
        refund-payment-gateway-priorities:
          - ...
          - PAYPAL_CHECKOUT_V2
          - ...