How to Set Up a Payment Preapproval 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.

To set up a payment preapproval by using Adaptive Payments, you must:

  1. Set up the preapproval.
  2. Redirect the customer to PayPal for authorization.
  3. Optionally, retrieve data about the preapproval.
  4. Optionally, capture a future payment.

When you use Adaptive Payments to set up payment preapprovals, the payment amounts can vary frequently. For additional information about the subjects covered below, see the following:

Note: Please see Going Live with Your Application regarding the review process for applications.

Step 1: Set Up the Preapproval

When a customer is ready to authorize a preapproval, use the Preapproval call. The input includes a start date for the preapproval. The Preapproval response contains a preapproval key (in the preapprovalKey field) for use in subsequent steps. For parameter descriptions, see the Preapproval API Operation.

The following HTTP POST request includes cURL syntax.

HTTP Headers
------------
-H "X-PAYPAL-SECURITY-USERID: insert_developer_user_name"
-H "X-PAYPAL-SECURITY-PASSWORD: insert_developer_password"
-H "X-PAYPAL-SECURITY-SIGNATURE: insert_developer_signature"
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
-H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T"    #Standard Sandbox App ID

Endpoint
--------
https://svcs.sandbox.paypal.com/AdaptivePayments/Preapproval

Input Parameters
----------------
returnUrl=https://example.com/success   #For use if the customer proceeds with approval
&cancelUrl=https://example.com/cancel   #For use if the customer decides not to proceed with approval
&startingDate=2012-04-27T10:45:52Z    #First date on which the preapproval is valid
&endingDate=2013-02-02T20:40:52Z    #Last date on which the preapproval is valid
&maxAmountPerPayment=35.00    #The maximum amount per payment under the preapproval
&maxNumberOfPayments=20    #The maximum number of payments under the preapproval
&maxTotalAmountOfAllPayments=800.00    #The max of all payments; must be less than, or equal to, $2,000 (or equivalent)
¤cyCode=USD    #The currency, e.g. US dollars
&requestEnvelope.errorLanguage=en_US

Response
--------
responseEnvelope.ack=Success
&preapprovalKey=PA-5KY19448VE6821234    #Value of the preapproval key, for use in subsequent steps
...

Step 2: Redirect the Customer to PayPal for Authorization

To redirect the customer for authorization, use the preapproval key from the Preapproval response (Step 1), with the PayPal authorization URL:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=InsertPreapprovalKeyHere

If the customer authorizes the payment, the customer is redirected to the return URL (specified in the Preapproval call). Otherwise, the customer is redirected to the cancel URL (also specified in the Preapproval call), so you can provide a way to re-initiate a preapproval.

Step 3: Retrieve Data about the Preapproval (Optional)

If you want to retrieve data about a customer's preapproval, specify the preapproval key (from Step 1) in a PreapprovalDetails call. For more information, see the PreapprovalDetails API Operation.

The following HTTP POST request includes cURL syntax.

HTTP Headers
------------
-H "X-PAYPAL-SECURITY-USERID: insert_developer_user_name"
-H "X-PAYPAL-SECURITY-PASSWORD: insert_developer_password"
-H "X-PAYPAL-SECURITY-SIGNATURE: insert_developer_signature"
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
-H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T"    #Standard Sandbox App ID

Endpoint
--------
https://svcs.sandbox.paypal.com/AdaptivePayments/PreapprovalDetails

Input Parameters
----------------
preapprovalKey=PA-5PU68213WY5961234    #Value of the preapproval key, received in the Preapproval call above
&requestEnvelope.errorLanguage=en_US

Response
--------
&responseEnvelope.ack=Success
&approved=true
&cancelUrl=http%3A%2F%2Fwww.yourdomain.com%2Fcancel.html
&curPayments=0
&curPaymentsAmount=0.00
&curPeriodAttempts=0
¤cyCode=USD
&dateOfMonth=0
&dayOfWeek=NO_DAY_SPECIFIED
&endingDate=2013-02-02T20%3A40%3A52.000Z
&maxAmountPerPayment=35.00
&maxNumberOfPayments=20
&maxTotalAmountOfAllPayments=800.00
&paymentPeriod=NO_PERIOD_SPECIFIED
&pinType=NOT_REQUIRED
&returnUrl=http%3A%2F%2Fwww.yourdomain.com%2Fsuccess.html
&senderEmail=insert_sender_email
&startingDate=2012-05-03T10%3A27%3A52.000Z
&status=ACTIVE
&displayMaxTotalAmount=false
...

Step 4: Capture a Future Payment (Optional)

For a future payment that is based on the preapproval, use the Pay call. In the Pay call request, include the preapproval key received in the Preapproval response (Step 1). The Pay call can be used for a simple, parallel, or chained payment. For more information, see the Pay API Operation.

The following HTTP POST request includes cURL syntax.

HTTP Headers
------------
-H "X-PAYPAL-SECURITY-USERID: insert_developer_user_name_here"
-H "X-PAYPAL-SECURITY-PASSWORD: insert_developer_password_here"
-H "X-PAYPAL-SECURITY-SIGNATURE: insert_developer_signature_here"
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
-H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T"     #Standard Sandbox App ID

Endpoint
--------
https://svcs.sandbox.paypal.com/AdaptivePayments/Pay

Input Parameters
----------------
actionType=PAY     #The action taken in the Pay request (that is, the PAY action)
¤cyCode=USD    #The currency, e.g. US dollars
&feesPayer=EACHRECEIVER
&memo=Example
&preapprovalKey=PA-5KY19448VE6821234    #The preapproval key received in a Preapproval API response
&receiverList.receiver(0).amount=7.00    #The payment amount
&receiverList.receiver(0).email=insert_email_of_receiver
&senderEmail=insert_email_of_sender
&returnUrl=https://example.com/success   #For use if the customer proceeds with payment
&cancelUrl=https://example.com/cancel    #For use if the customer decides not to proceed with payment
&requestEnvelope.errorLanguage=en_US

Response
--------
responseEnvelope.ack=Success
&payKey=AP-7L748474VE7451234    #Value of the pay key, e.g. for use in a PaymentDetails call
&paymentExecStatus=COMPLETED
...