PayPal Commerce Checkout (SDK)

You may implement PayPal’s SDK to take advantage of Venmo and Pay Later payment options through PayPal. Other payment options are coming soon.

Full PayPal documentation on this approach is here:

PayPal SDK: https://developer.paypal.com/sdk/js/reference/

SDK Performance Optimization: https://developer.paypal.com/sdk/js/performance/

The PayPal SDK supports PayPal, Venmo, and Pay Later only
If you are not implementing Venmo or Pay Later then do not use the SDK. Follow these instructions instead.
The PayPal option cannot be disabled (you cannot offer Venmo or Pay Later without a PayPal button on your page).
The PayPal SDK is supported only when referenceTransactions is disabled OR referenceTransactions and vaultEnabled are both enabled.
Pay Later is not compatible with the Single Transaction campaign option
You cannot choose different payment types for checkout and upsells. For example, if a checkout is done on Venmo then the upsell must also be on Venmo.
Rebills are supported on Venmo when referenceTransactions and vaultEnabled are both enabled. Rebills are never supported on Pay Later.

Checkout Page

Step 1: Import Click

The Checkout page contains the PayPal SDK. Call the Import Click API when the page loads to obtain a session.

Be sure to include pageType=checkoutPage and sessionId

If this is the first page of the funnel -

Send requestUri (include affiliate tracking string for reporting) instead of sessionId.

The response from this call will contain a sessionId which should be sent on all subsequent API calls for this session.

Step 2: PayPal SDK

Add this required script to the checkout page

Mandatory Parameters:

CLIENT_ID:
- Live: AWGTxJ1AlWxI4ZyxZ8J-Mrc_gkVkPR-CFBcT4UnlYUFvEulP6ItFrm_DnLhpZ7dlB94KhqFGd3t7dMQs
- Sandbox: AdATBZ6vUtyH5FQ3weG-63lWwkNioUYJ0b07KEdVwrw0z_DkctGqnz2Q7O-59Dh5nLAOo0LsQOw5GTqY
MERCHANT_ID: Your PayPal gateway "merchantId"
CURRENCY: Campaign Currency code (such as USD)
ENABLED_FUNDINGS: venmo, paylater. Only venmo and paylater are supported. You can remove venmo or paylater if you do not want to offer both types. For upsell pages this should include only the type chosen at checkout.
DISABLE_FUNDING: Not all PayPal payment sources are supported. You may need to explicitly disable some options. This should be a comma-separated list of:
card
bancontact
blik
eps
giropay
ideal
mercadopago
mybank
p24
sepa
sofort
credit (do not include this if paylater is enabled)
venmo (do not include this if venmo is enabled)
paylater (do not include this if paylater is enabled)
PARTNER_ID:
- Live: 77XY5SSCLTNTY
- Sandbox: T2PHJAU4MDP4J

Conditional Parameter:

If QA or Capture on Shipment is enabled in the campaign then include intent=authorize
- PayPal SDK will not work with multiple transactions. Do not use Capture on Shipment with both a physical and digital product on the order. Those will be separate transactions.

See this link for full details: JavaScript SDK script configuration

Step 3: PayPal button

Add a button to the body tag with an "id" attribute (example: id: paypal-button-container)

Step 4: Handle PayPal button functions

Functions required for the PayPal buttons are:

onClick (Call the Import Order API to retrieve the create order parameters. It must include paypalSdk = 1 with other required parameters)
1. It is important that you bind the Import Order call to the PayPal checkout button.
  - Be sure to include the sessionId and orderId from the previous steps, if known
2. There are PayPal specific requirements that need to be passed to Import Order:
  1. paySource = 'PAYPAL'
  2. paypalBillerId is the value assigned to your PayPal Commerce gateway, found on your gateway list.
  3. prepaidType = PAYPAL_VENMO or PAYPAL_PAYLATER (if PayPal button is clicked then do not send this parameter)
  4. salesUrl = the checkout page full url
createOrder (Create a PayPal order using the parameters received from the “onClick” function)
onApprove (PayPal approved the order. To process the order in CheckoutChamp and complete it in PayPal pass the “orderID” and “payerID” to Confirm PayPal API. It must include paypalSdk = 1)
onCancel (PayPal users canceled the payment or closed the payment screen)
onError (Error from PayPal)

See this link for more details: JavaScript SDK reference

Step 5: Upsell Pages

It is not necessary to render the PayPal SDK on upsell pages when checkout is done with PayPal or Venmo AND referenceTransactions is enabled AND vaultEnabled is enabled. In this situation the upsell will be processed with a one-click flow.

For all other situations the previous steps can be repeated on each upsell page. In these situations the PayPal SDK does not support a one-click upsell.

Checkout page example:

<!DOCTYPE html>
<html>
    <head>
        <title>PayPal SDk Integration</title>
        <script src="https://www.paypal.com/sdk/js?client-id=<CLIENT_ID>&merchant-id=<MERCHANT_ID>&currency=<CURRENCY>&enable-funding=<ENABLED_FUNDINGS>&disable-funding=card" data-partner-attribution-id="<PARTNER_ID>"></script> 
    </head>
    <body>
    
        <div id="paypal-button-container"></div>
        
        <script>
            var paypalSdkParams = null;
            var paypalPrePaidType = null;
            paypal.Buttons({
                style: {
                    layout: 'vertical',
                    label:  'paypal'
                },
                onClick: function(data, actions) {
                    try {
                        var fundingSource = data && data.fundingSource && data.fundingSource.toUpperCase(); 
                        if (["VENMO", "PAYLATER"].includes(fundingSource)) {
                            paypalPrePaidType = "PAYPAL_" + fundingSource;
                        }
                        // Call the import order API with the required parameters and additional pass "paypalSdk=1" and "prepaidType=paypalPrePaidType" in the request.
                        if (res && res.result === "SUCCESS" && res.message && res.message.paypalSdkParams) {
                            paypalSdkParams = res.message.paypalSdkParams;
                            return actions.resolve();
                        } else {
                            return actions.reject();
                        }
                    } catch(err) {
                        // Handle error 
                    }
                },
                createOrder: function(data, actions) {
                    try {
                        const orderId = paypalSdkParams && paypalSdkParams.id;
                        if (!orderId) throw new Error("Insufficient data to process PayPal checkout.");
                        return orderId;
                    } catch(err) {
                        // Handle error for missing order id
                    }
                },
                onApprove: function(data, actions) {
                    try {
                        // Call confirm PayPal API with the required parameters and additional pass following parameters
                        // 1. token: data.orderID
                        // 2. payerId: data.payerID
                        // 3. paypalSdk: 1
                        // 4. prepaidType: paypalPrePaidType;
                        // Note the prepaidType passed to import order API must match with the prepaid type passed on to confirm PayPal API. 
                    } catch (err) {
                        throw new Error("Error: Unable to confirm order.");
                    }
                },
                onCancel: function (data) {
                    // Payment cancelled by the customer. 
                },
                onError: function (err) {
                    // Error from PayaPal. 
                }
            }).render('#paypal-button-container');
        </script>
    </body>
</html>

Upsell page example:

<!DOCTYPE html>
<html>
    <head>
        <title>PayPal SDk Integration</title>
        <!-- Note: On the upsell page, only enable funding sources, which were used to complete transactions on the checkout page. Set other funding sources to disable-funding parameter. -->
        <!-- The checkout page funding source can be retrieved from prepaidType in the Import Order response -->
        <script src="https://www.paypal.com/sdk/js?client-id=<CLIENT_ID>&merchant-id=<MERCHANT_ID>&currency=<CURRENCY>&enable-funding=<ENABLED_FUNDINGS>&disable-funding=card" data-partner-attribution-id="<PARTNER_ID>"></script> 
    </head>
    <body>
    
        <div id="paypal-button-container"></div>
        
        <script>
            var paypalSdkParams = null;
            var paypalPrePaidType = null;
            paypal.Buttons({
                style: {
                    layout: 'vertical',
                    label:  'paypal'
                },
                onClick: function(data, actions) {
                    try {
                        var fundingSource = data && data.fundingSource && data.fundingSource.toUpperCase(); 
                        if (["VENMO", "PAYLATER"].includes(fundingSource)) {
                            paypalPrePaidType = "PAYPAL_" + fundingSource;
                        }
                        // On upsell page match checkout page prepaid type with funding source clicked on upsell page. If not reject payment process.
                        var orderData = sessionStorage.getItem("orderData") ? JSON.parse(sessionStorage.getItem("orderData")) : null
                        var orderPrepaidType = orderData && orderData.prepaidType;
                        if (orderPrepaidType !== paypalPrePaidType) {
                            return actions.reject();
                        }
                        // Call the import upsale API with the required parameters and additional pass "paypalSdk=1" in the request.
                        if (res && res.result === "SUCCESS" && res.message && res.message.paypalSdkParams) {
                            paypalSdkParams = res.message.paypalSdkParams;
                            return actions.resolve();
                        } else {
                            return actions.reject();
                        }
                    } catch(err) {
                        // Handle error 
                    }
                },
                createOrder: function(data, actions) {
                    try {
                        const orderId = paypalSdkParams && paypalSdkParams.id;
                        if (!orderId) throw new Error("Insufficient data to process PayPal checkout.");
                        return orderId;
                    } catch(err) {
                        // Handle error for missing order id
                    }
                },
                onApprove: function(data, actions) {
                    try {
                        // Note: Similar to the onclick method, re-check the checkout page prepaid type with the funding source after approval on the upsell page. If the funding source does match, do not call the confirm PayPal API and throw custom error as done in catch block.
                        // Call confirm PayPal API with the required parameters and additional pass following parameters
                        // 1. token: data.orderID
                        // 2. payerId: data.payerID
                        // 3. paypalSdk: 1
                        // 4. prepaidType: paypalPrePaidType; 
                    } catch (err) {
                        throw new Error("Error: Unable to confirm order.");
                    }
                },
                onCancel: function (data) {
                    // Payment cancelled by the customer. 
                },
                onError: function (err) {
                    // Error from PayaPal. 
                }
            }).render('#paypal-button-container');
        </script>
    </body>
</html>

Single Transaction

The Single Transaction feature works with the PayPal SDK when referenceTransactions and vaultEnabled are both enabled. Single Transaction works only for PayPal and Venmo payment types.