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 pre-approval by using Adaptive Payments, you must:

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

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

Note: For the review process for apps, see Go Live with Your App.

Step 1: Set Up the Preapproval

When a customer is ready to authorize a pre-approval, use the Preapproval call. The input includes a start date for the pre-approval. The Preapproval response contains a pre-approval 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 pre-approval is valid
&endingDate=2013-02-02T20:40:52Z    #Last date on which the pre-approval is valid
&maxAmountPerPayment=35.00    #The maximum amount per payment under the pre-approval
&maxNumberOfPayments=20    #The maximum number of payments under the pre-approval
&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 pre-approval key, for use in subsequent steps
...

Step 2: Redirect the Customer to PayPal for Authorization

To redirect the customer for authorization, use the pre-approval 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 pre-approval.

Step 3: Retrieve Data about the Preapproval (Optional)

If you want to retrieve data about a customer's pre-approval, specify the pre-approval 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 pre-approval 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 pre-approval, use the Pay call. In the Pay call request, include the pre-approval 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 pre-approval 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
...
Feedback

Have feedback?

Let us know.