How to Make a Delayed Chained Payment 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 make a delayed chained payment using Adaptive Payments:

  1. Set up the payment.
  2. Redirect the customer to PayPal for authorization.
  3. Optionally, retrieve data about the payment to the primary receiver.
  4. Make a payment to all secondary receivers (that is, to one or more secondary receivers).

Call the Pay operation as described below for a payment to a primary receiver. After customer authorization, the primary receiver is paid. Payments to secondary receivers can be delayed for up to 90 days. 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 that include chained payments or other advanced functionality.

Step 1: Set Up the Payment

When a customer is ready to check out, use the Pay call to set up the delayed chained payment. Use an actionType of PAY_PRIMARY to specify that payment is made to the primary receiver but not to the secondary receivers.

The Pay response contains a pay key for use in subsequent steps. For parameter descriptions, 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_PRIMARY     #The PAY_PRIMARY action type delays payment to non-primary receivers
&clientDetails.applicationId=APP-80W284485P519543T     #Standard Sandbox App ID
&clientDetails.ipAddress=127.0.0.1     #Address from which request is sent
¤cyCode=USD    #The currency, e.g. US dollars
&feesPayer=EACHRECEIVER
&memo=Example
&receiverList.receiver(0).amount=25.00    #The payment amount for the first receiver
&receiverList.receiver(0).email=insert_email_of_receiver1
&receiverList.receiver(0).primary=true    #Receiver designation (there can be only 1 primary receiver)
&receiverList.receiver(1).amount=5.00    #The payment amount for the second receiver
&receiverList.receiver(1).email=insert_email_of_receiver2
&receiverList.receiver(1).primary=false
&requestEnvelope.errorLanguage=en_US
&returnUrl=https://example.com/success   #For use if the consumer proceeds with payment
&cancelUrl=https://example.com/cancel    #For use if the consumer decides not to proceed with payment

Response
--------
responseEnvelope.ack=Success
&payKey=AP-9HY848657G6071234    #Value of the pay key, for use in a redirect to the PayPal site
&paymentExecStatus=CREATED    #Indicates that a payment is set up, ready for a sender to click Pay on the PayPal site
...

Step 2: Redirect the Customer to PayPal for Authorization

Redirect the customer to Paypal by using the URL-decoded pay key from Step 1, with the PayPal authorization URL, as follows:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-payment&paykey=InsertPayKeyHere

If the customer doesn't provide authorization, the customer is redirected to the cancel URL that you specified in the Pay call, so you can provide a way to re-initiate checkout.

If the customer authorizes the payment, the customer is redirected to the return URL that you specified in the Pay call.

Step 3: Retrieve Data about the Payment (Optional)

Optionally, call PaymentDetails to get data about the payment, specifying the pay key from Step 1. The PaymentDetails response should indicate that the secondary receiver has not yet been paid (i.e, the status value is INCOMPLETE, as shown in the following sample). For additional information about this call, see the PaymentDetails API Operation.

Note that after an ExecutePayment call (see Step 4), a PaymentDetails response would indicate that the secondary receivers were paid.

The following sample represents a PaymentDetails call that is made before an ExecutePayment call.

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/PaymentDetails

Input Parameters
----------------
payKey=AP-9HY848657G6071234    #Value of the pay key, received in the Pay call above
&requestEnvelope.errorLanguage=en_US

Response
--------
responseEnvelope.ack=Success
&cancelUrl=http%3A%2F%2Fwww.yourdomain.com%2Fcancel.html
&returnUrl=http%3A%2F%2Fwww.yourdomain.com%2Fsuccess.html
¤cyCode=USD
&memo=example
&paymentInfoList.paymentInfo(0).transactionId=9EM14068G28701234
&paymentInfoList.paymentInfo(0).transactionStatus=COMPLETED
&paymentInfoList.paymentInfo(0).receiver.amount=25.00
&paymentInfoList.paymentInfo(0).receiver.email=email_of_receiver_number_1
&paymentInfoList.paymentInfo(0).receiver.primary=true
&paymentInfoList.paymentInfo(0).receiver.paymentType=SERVICE
&paymentInfoList.paymentInfo(0).refundedAmount=0.00
&paymentInfoList.paymentInfo(0).pendingRefund=false
&paymentInfoList.paymentInfo(0).senderTransactionId=66E25325WG7781234
&paymentInfoList.paymentInfo(0).senderTransactionStatus=COMPLETED
&paymentInfoList.paymentInfo(1).receiver.amount=5.00
&paymentInfoList.paymentInfo(1).receiver.email=email_of_receiver_number_2
&paymentInfoList.paymentInfo(1).receiver.primary=false
&paymentInfoList.paymentInfo(1).receiver.paymentType=SERVICE
&paymentInfoList.paymentInfo(1).refundedAmount=0.00
&paymentInfoList.paymentInfo(1).pendingRefund=false
&status=INCOMPLETE    #Indicates that the secondary receiver has not been paid
&payKey=AP-9HY848657G6071234
&actionType=PAY_PRIMARY
&feesPayer=EACHRECEIVER
&reverseAllParallelPaymentsOnError=false
&sender.email=sender_email
&sender.useCredentials=false
...

Step 4: Make a Payment to One or More Secondary Receivers

When the time comes to pay secondary receivers, call ExecutePayment, specifying the pay key from Step 1. For more information on this call, see the ExecutePayment API Operation.

When the time comes to pay secondary receivers, all secondary receivers must be paid at once.

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/ExecutePayment

Input Parameters
----------------
payKey=AP-9HY848657G6071234    #Value of the pay key, received in the Pay call above
&requestEnvelope.errorLanguage=en_US

Response
--------
responseEnvelope.ack=Success
&paymentExecStatus=COMPLETED
...