Adaptive Payment Commands and Redirects
Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations.
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 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
|
isOpen:
function () |
Determine whether the mini-browser or lightbox is still open. |