How to Make a Basic 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 basic chained payment using Adaptive Payments, you must:

  1. Set up the payment.
  2. Redirect the customer to PayPal for authorization.
  3. Optionally, retrieve information about the payment.

In a chained payment, a payment is made to a primary receiver. The primary receiver keeps some of the payment and pays the rest to one or more secondary receivers. 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 chained payment. The input fields include the email address of a single primary receiver and the email addresses of one or more secondary receivers. Also specify the payment amounts.

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     #The action taken in the Pay request (that is, the PAY action)
&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=21.00    #The payment amount for the first receiver 
&receiverList.receiver(0).email=insert_email_of_receiver_number_1
&receiverList.receiver(0).primary=true    #Receiver designation (there can be only 1 primary receiver)
&receiverList.receiver(1).amount=11.00    #The payment amount for the second receiver
&receiverList.receiver(1).email=insert_email_of_receiver_number_2
&receiverList.receiver(1).primary=false    
&requestEnvelope.errorLanguage=en_US
&returnUrl=http://www.yourdomain.com/success.html   #For use if the consumer proceeds with payment
&cancelUrl=http://www.yourdomain.com/cancel.html    #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 Information about the Payment (Optional)

If you want to retrieve data about the payment, specify the pay key (from Step 1) in a PaymentDetails call. The PaymentDetails call enables you to obtain transaction IDs and other information about the payment. For more information, see PaymentDetails 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/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=1WM04897AU5801234
&paymentInfoList.paymentInfo(0).transactionStatus=COMPLETED
&paymentInfoList.paymentInfo(0).receiver.amount=21.00
&paymentInfoList.paymentInfo(0).receiver.email=email_of_receiver1
&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=53229263MA6891234
&paymentInfoList.paymentInfo(0).senderTransactionStatus=COMPLETED
&paymentInfoList.paymentInfo(1).transactionId=01J42049BN9361234
&paymentInfoList.paymentInfo(1).transactionStatus=COMPLETED
&paymentInfoList.paymentInfo(1).receiver.amount=11.00
&paymentInfoList.paymentInfo(1).receiver.email=email_of_receiver2
&paymentInfoList.paymentInfo(1).receiver.primary=false
&paymentInfoList.paymentInfo(1).receiver.paymentType=SERVICE
&paymentInfoList.paymentInfo(1).refundedAmount=0.00
&paymentInfoList.paymentInfo(1).pendingRefund=false
&paymentInfoList.paymentInfo(1).senderTransactionId=9SS52070LM9691234
&paymentInfoList.paymentInfo(1).senderTransactionStatus=COMPLETED
&status=COMPLETED
&payKey=AP-9HY848657G6071234
&actionType=PAY
&feesPayer=EACHRECEIVER
&reverseAllParallelPaymentsOnError=false
&sender.email=sender_email
&sender.useCredentials=false
...