How to Create an Embedded Payment Flow Using Adaptive Payments

Important: Adaptive Payments is now a limited release product. It is restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.

An embedded payment flow enables users to pay without appearing to leave your site or app.

An embedded payment flow can be used for simple, parallel, and chained payments. For more information, see the "Embedded Payments" section of Introducing Adaptive Payments.

Options for an Embedded Payment Flow

As shown in the examples at Introducing Adaptive Payments, an embedded payment flow can be implemented in two ways:

Implementing the Lightbox Option

Lightbox functionality requires the following steps. For information about digital goods payments, see the "Payments for Digital Goods" section in the Pay API reference documentation.

Step 1: Obtain a Pay Key

Use the Pay operation to set up a simple, parallel, or chained payment. The Pay response contains a payKey value. The following document shows an example:

Step 2: Create an HTML Form for Initiating the Lightbox

Create a new HTML file and paste the following code into the file.

<html>
<head>
<script src="https://www.paypalobjects.com/js/external/dg.js" type="text/javascript"></script>
</head>

<body>
<form action="https://www.sandbox.paypal.com/webapps/adaptivepayment/flow/pay" target="PPDGFrame" class="standard">
<label for="buy">Buy Now:</label>
<input type="image" id="submitBtn" value="Pay with PayPal" src="https://www.paypalobjects.com/en_US/i/btn/btn_paynowCC_LG.gif">
<input id="type" type="hidden" name="expType" value="light">
<input id="paykey" type="hidden" name="paykey" value="insert_pay_key">
</form>

<script type="text/javascript" charset="utf-8">
var embeddedPPFlow = new PAYPAL.apps.DGFlow({trigger: 'submitBtn'});
</script>
</body>

</html>

The sample above shows the functionality for a final payment page (checkout page). This sample includes a reference to the necessary javascript (https://www.paypalobjects.com/js/external/dg.js).

Your implementation will vary.

For passing the payKey value to the PayPal sandbox, the form-action handler is set, as follows:

<form action="https://www.sandbox.paypal.com/webapps/adaptivepayment/flow/pay" target="PPDGFrame" class="standard">

When the user clicks the button on the form, the PAYPAL.apps.DGFlow object is created, because you attached it as a trigger to the button:

var embeddedPPFlow = new PAYPAL.apps.DGFlow({trigger: 'submitBtn'});

The expType variable is set to light, so a test user will use a lightbox to complete authorization in the PayPal sandbox at https://www.sandbox.paypal.com/webapps/adaptivepayment/flow/pay.

Step 3: Insert a Pay Key into the HTML Form

For the payKey input value, replace insert_pay_key with a payKey value that you recently obtained using a Pay call, and save the HTML file.

Step 4: Test the HTML Form

Open the HTML file in a browser and click Pay Now to test the lightbox:

lightbox

Next steps

Please see Going Live with Your Application regarding the review process for applications that include adaptive payments or other advanced functionality.

Implementing the Mini-Browser Option

Mini-browser functionality requires the following steps. For information about digital goods payments, see the "Payments for Digital Goods" section in the Pay API reference documentation.

Step 1: Obtain a Pay Key

Use the Pay operation to set up a simple, parallel, or chained payment. The Pay response contains a payKey value. The following document shows an example:

Step 2: Create an HTML Form for Initiating the Mini-Browser

Create a new HTML file and paste the following code into the file.

<html>
<head>
<script src="https://www.paypalobjects.com/js/external/apdg.js" type="text/javascript"></script>
</head>

<body>
<form action="https://www.sandbox.paypal.com/webapps/adaptivepayment/flow/pay" target="PPDGFrame" class="standard">

<label for="buy">Buy Now:</label>
<input type="image" id="submitBtn" value="Pay with PayPal" src="https://www.paypalobjects.com/en_US/i/btn/btn_paynowCC_LG.gif">
<input id="type" type="hidden" name="expType" value="mini">
<input id="paykey" type="hidden" name="paykey" value="insert_pay_key">
</form>
<script type="text/javascript" charset="utf-8">
var dgFlowMini = new PAYPAL.apps.DGFlowMini({trigger: 'submitBtn'});
</script>
</body>

</html>

The previous sample shows the functionality for a final payment page (checkout page). This sample includes a reference to the necessary javascript (https://www.paypalobjects.com/js/external/apdg.js).

Your implementation will vary.

For passing the payKey value to the PayPal sandbox, the form-action handler is set, as follows:

<form action="https://www.sandbox.paypal.com/webapps/adaptivepayment/flow/pay" target="PPDGFrame" class="standard">

When the user clicks the button on the form, the PAYPAL.apps.DGFlowMini object is created, because you attached it as a trigger to the button. The variable used for the PAYPAL.apps.DGFlowMini object must be named dgFlowMini:

var dgFlowMini = new PAYPAL.apps.DGFlowMini({trigger: 'submitBtn'});

The expType variable is set to mini, so a test user will use a mini-browser to complete authorization in the PayPal sandbox at https://www.sandbox.paypal.com/webapps/adaptivepayment/flow/pay.

Step 3: Insert a Pay Key into the HTML Form

For the payKey input value, replace insert_pay_key with a payKey value that you recently obtained using a Pay call, and save the HTML file.

Step 4: Test the HTML Form

As a test, open the HTML file in a browser and click Pay Now:

Next steps

For information about the review process for applications that include adaptive payments or other advanced functionality, see Going Live with Your Application.