How to Create an Embedded Payment Flow Using Adaptive Payments
Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations.
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:
- The lightbox option provides the embedded payment flow as an overlay.
- The mini-browser option provides the embedded payment flow in a mini-browser window.
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:
Next steps
Please see Go Live with Your App 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 Go Live with Your App.