PayPal

This documentation is intended for merchants integrating ePay Blocks directly. If you are using ePay Checkout, no additional PayPal integration changes are required here.

We recommend that all merchants use the Quick Setup guide, as it reduces the maintenance burden on your integration. By using Quick Setup, ePay can automatically apply updates to your integration for future changes to the PayPal flow.

Quick Setup

To integrate PayPal, add a mount target for the button and let ePay mount the PayPal button for the current payment session.

<script async    src="https://www.paypal.com/web-sdk/v6/core"    onload="epay.onPayPalLoaded()"></script>...<div id="paypal-button"></div>...epay.mountPayPalButton("paypal-button", {    style: {        color: "gold",        shape: "pill",        label: "pay",    },});

Bring your own button

If you do not want to use the native PayPal button, you instead can style the PayPal button yourself and onclick call the epay.createPayPalTransaction() to create the order and start the PayPal payment flow.

<script async    src="https://www.paypal.com/web-sdk/v6/core"    onload="epay.onPayPalLoaded()"></script>...<button onclick="epay.createPayPalTransaction()">PayPal</button>

Button customization

The second argument to mountPayPalButton(target, buttonOptions, paymentOptions) is passed directly to paypal.Buttons(...). Use this for standard button customization such as style and other appearance-related PayPal button settings. The PayPal SDK might take a second to load the first time, so you can set a spinner while the button is loading, it being enabled by default. Avoid overriding flow callbacks such as createOrder, onApprove, onCancel, and onError unless you intentionally want to replace parts of the default ePay flow.

epay.mountPayPalButton("paypal-button", {    style: {        color: "gold",        shape: "pill",        label: "pay",    },});

Advanced usage

The primary integration method is:

epay.mountPayPalButton(target, buttonOptions, paymentOptions);

Target

target can be either:

A string containing the id of the target element
An HTMLElement

Payment options

paymentOptions supports the same per-call overrides used by the ePay client. For PayPal, the main options are:

amount: used when the session supports dynamic amount

Flow details

When the PayPal button is mounted, ePay handles the standard flow for you:

Load the PayPal SDK based on the session payPalConfig
Create a PayPal order through ePay when the payer clicks the PayPal button
Stores the approved PayPal orderId on the session
Start the ePay transaction using the PAYPAL payment method

Notes and limitations

PayPal requires the payment session to contain a valid payPalConfig. If PayPal is not configured for the session, the button cannot be mounted.
PayPal is not available for fixed zero-amount sessions.
PayPal is not currently available for subscription sessions.
paymentCancel is dispatched when the customer cancels the PayPal flow.
PayPal flow failures are dispatched through the generic error callback with PayPal-specific error messaging.

External references

PayPal JavaScript SDK overview