Frontend Integration

Note	If upgrading from PayPal Checkout JavaScript SDK v1, check out PayPal’s upgrade guide.

Broadleaf provides a PayPal Checkout SDK for common interactions with the PayPal JavaScript SDK.

To use the SDK in your frontend, you will need to handle several interactions. First, you’ll need to include the paypal sdk script during render at the top of your page. For example,

{PayPalConfig.CLIENT_ID && (
  <script
    data-csp-nonce={this.props.nonce}
    defer
    src={`https://www.paypal.com/sdk/js?client-id=${PayPalConfig.CLIENT_ID}&intent=authorize`}
  />
)}

Next, you’ll want to define the PayPal button on your checkout page.

Identify the button component after PayPal has loaded and render the button within your cart or checkout page.
Include any style or funding properties as needed.
1. For details on the funding parameters, see Funding Types defined in our PayPal Checkout SDK.
Provide callback functions for createOrder, onApprove, and onError.
1. For details on createOrder and handleApprove, see Handle Create Order and Handle Approve Order.
2. If using the Standard Paypal button flow, the handleApprove function should be responsible for calling PaymentTransactionServices to create & persist the payment.
  1. In the Standard flow, we render the buttons on the payment stage of checkout, alongside the credit card form & other available payment options.
3. If using the Express Paypal button flow, the handleApprove function should be responsible for updating the fulfillment information (i.e. shipping address), and then calling PaymentTransactionServices to create & persist the payment.
  1. The expectation in the express flow is that the checkout process is reduced to the minimum interactions for the customer. To achieve this, we use the shipping address selected within PayPal to populate our shipping & fulfillment information so that the customer can immediately enter the review stage of checkout.

Below is an example of using the PayPal button as a component within a React TypeScript application.

export const usePayPal = (): PayPalState => {
  const [state, setState] = useState<PayPalState>(
    isPayPalLoaded()
      ? { api: window['paypal'], button: getButtonComponent() }
      : {}
  );

  useEffect(() => {
    setState(
      isPayPalLoaded()
        ? { api: window['paypal'], button: getButtonComponent() }
        : {}
    );
  }, []);

  return state;
};

function isPayPalLoaded() {
  return window && window['paypal'];
}

function getButtonComponent() {
  return window['paypal'].Buttons.driver('react', { React, ReactDOM });
}

const { api, button: Button } = usePayPal();

return (
    <Button
      fundingSource={api.FUNDING[funding]}
      funding={api.FUNDING[funding]}
      createOrder={createOrder}
      onApprove={handleApprove}
      onError={error => {
        if (error.message === 'Expected an order id to be passed') {
          // don't want to show this message
          return;
        }

        setError(error.message);
      }}
      style={style}
    />
)

Building the payload to create the order in PayPal

When interacting with PayPal to create the order via their order create api, we have to consider how to map the data in our system over to a PayPal Order.

PayPal Create Order Request

intent [required]
1. Type: ENUM string
2. This can either be set to AUTHORIZE or CAPTURE, which determines which transaction type is executed in our checkout workflow.
purchase_units [required]
1. Type: Array of purchase unit requests
2. Each purchase unit is a list of data points that correlates to a payment in Broadleaf.
  1. amount: This is equivalent to the payment amount in Broadleaf. It can be broken down to include totals for items, discounts, shipping, and taxes.
  2. custom_id: This is an external id which Broadleaf populates with the {cartId}-{currentTimestamp} by default. This is used by our system as the transaction reference id, which allows us to reference the transaction if we do not receive a response back from the payment gateway during transaction execution.
  3. items: The list of cart items for the order, populated by cart items on Broadleaf’s cart representation.
  4. shipping: The shipping address for the order. By default, this is populated from Broadleaf’s shipping address stored on the fulfillment group. Sending this field to PayPal is optional.
  5. Refer to PayPal docs for additional fields on purchase unit request which can be populated as your implementation requires.