On this page
No Headings
Last updated: August 17, 2026
Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations. If you're starting an integration, we recommend our latest solutions.
The web flows associated with Adaptive Payments may require you to redirect a
sender's browser to PayPal. When you redirect to the
webscr endpoint, you must send a command that identifies the flow
and associated parameters, or in the case of the embedded payment flow, you
must redirect to a specific endpoint for the flow.
When redirecting to https://www.paypal.com/cgi-bin/webscr, you
must specify a command that identifies the flow.
| Command | Description |
|---|---|
_ap-payment | Invokes PayPal login to approve a payment using Adaptive Payments |
_ap-preapproval | Invokes PayPal login to set up a preapproval using Adaptive Payments |
The sender can log in to paypal.com and approve a payment when you redirect
the sender's browser to paypal.com with the _ap-payment command.
https://www.paypal.com/cgi-bin/webscr?cmd=_ap-payment&paykey=value
| Parameter | Description |
|---|---|
| cmd | (Required) _ap-payment |
| paykey | (Required) The payment key from the Pay response message; for example, AP-12345678901234567. |
PayPal redirects to the return URL you set in the Pay request.
Note: Any additional parameters you specify in the URL are not returned.
The sender can log in to paypal.com and approve a preapproval request when you
redirect the sender's browser to PayPal using the
_ap-preapproval command.
https://www.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=value
| Parameter | Description |
|---|---|
| cmd | (Required) _ap-preapproval |
| preapprovalkey | (Required) The preapproval key from the Preapproval response message; for example, PA-12345678901234567. |
PayPal redirects to the return URL you set in the
Preapproval request.
Note: Any additional parameters you specify in the URL are not returned.
The sender of a payment can log in to paypal.com and approve a payment using the embedded payment flow. Your web pages must use PayPal-provided JavaScript to launch the flow.
https://www.paypal.com/webapps/adaptivepayment/flow/pay? paykey=value&preapprovalkey=value
| Parameter | Description |
|---|---|
| paykey | (Required) The payment key from the Pay response message; for example, AP-12345678901234567. |
| preapprovalkey | (Optional) The preapproval key from the Preapproval response message, which enables the Preapprove future payments option; for example, PA-12345678901234567. |
PayPal redirects to the return URL you set in the Pay request.
Note: Any additional parameters you specify in the URL are not returned.
You must include https://www.paypalobjects.com/js/external/dg.js,
for a lightbox, or
https://www.paypalobjects.com/js/external/apdg.js, for a
mini-browser, on any page that invokes or terminates the embedded payment
flow. The JavaScript functions in dg.js and
apdg.js set up and control the PayPal login and payment
experience.
| Function and Signature | Description |
|---|---|
PAYPAL.apps.DGFlow = function (trigger: null, expType: null) or PAYPAL.apps.DGFlowMini = function (trigger: null, expType: null) | Sets up the embedded payment flow, where trigger is one or more HTML IDs of events that trigger the flow and expType is one of the following experience type requests:
light. Opening a mini-browser in a lightbox causes errors during the flow. Note: PayPal does not honor the lightbox experience request if the sender is required to log into PayPal. |
setTrigger: function (id) | Add a trigger for the flow, where id is the HTML id of the event that triggers the flow. The flow must first be set up by calling PAYPAL.apps.DGFlow. |
startFlow: function (url) | Explicitly start the embedded payment flow, where url is the URL that triggers the flow. Note: You are only required to explicitly start the flow when there is no triggering event; for example, when you want to associate the embedded payment flow with playing a Flash movie. |
closeFlow: function () | Close the mini-browser or lightbox associated with the flow. Use this function after the sender completes or cancels the payment. Note: In addition to calling this function, you must explicitly close the PayPal window using the close() JavaScript function. |
isOpen: function () | Determine whether the mini-browser or lightbox is still open. |