Adaptive Payment Commands and Redirects

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.

Adaptive Payment Commands

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

_ap-payment Command

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.

Redirect to PayPal using 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.

Response to _ap-payment command from PayPal

PayPal redirects to the return URL you set in the Pay request.

Note: Any additional parameters you specify in the URL are not returned.

_ap-preapproval Command

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.

Redirect 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.

Response to _ap-preapproval command from PayPal

PayPal redirects to the return URL you set in the Preapproval request.

Note: Any additional parameters you specify in the URL are not returned.

Embedded Payment Flow Redirect

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.

Redirect to PayPal

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.

Response from PayPal

PayPal redirects to the return URL you set in the Pay request.

Note: Any additional parameters you specify in the URL are not returned.

JavaScript Functions for Embedded Payments

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 minibrowser, 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 requests that the embedded payment flow displays in a lightbox (default)
  • mini requests that the embedded payment flow displays in a minibrowser
For information about how to use the lightbox and minibrowser options, see How to Create an Embedded Payment Flow Using Adaptive Payments. PayPal handles other values, including misspellings, as light. Opening a minibrowser 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 minibrowser 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 minibrowser or lightbox is still open.