How to Make Parallel Payments Using Express Checkout

Parallel payments enable buyers to submit a single payment for good or services provided by two or more merchants.

For example, suppose you have a website that lets customers charter sailboat rides. To enhance their experience, customers can add a meal to their ride through a third-party vendor. By using parallel payments, customers make a single payment to purchase both the sailboat ride and the catered meal. In this scenario, one portion of the payment goes to your charter company while a second portion of the payment goes to the caterer.

Process Overview

While parallel payments follow the normal Express Checkout flow, they differ in the following ways:

  • The SetExpressCheckout request includes different items offered by multiple merchants.
  • The SetExpressCheckout request contains primary information, as well as optional secondary information that adds detail to the items being purchased.
  • To capture the payment, your DoExpressCheckoutPayment request must itemize the different merchants and payment amounts.

Note: For instructions on using the PayPal APIs, how to use the Sandbox for testing, and how to move your app into production, see Apps 101.

To test parallel payments in the Sandbox, configure at least two sandbox business accounts (one for each merchant you want to simulate), as well as one Personal test account to represent the buyer.

Do It!

To make a parallel payment using Express Checkout:

  1. Initiate a SetExpressCheckout request:

    curl https://api-3t.sandbox.paypal.com/nvp \
      -s \
      --insecure \
      -d USER=Caller_ID                              # the PayPal User ID of the caller account \
      -d PWD=Caller_Pswd                             # the caller account Password \
      -d SIGNATURE=Caller_Sig                        # the caller account Signature \
      -d METHOD=SetExpressCheckout                   # API operation \
      -d RETURNURL=http://example.com/success.html   # URL displayed to buyer after authorizing transaction \
      -d CANCELURL=http://example.com/canceled.html  # URL displayed to buyer after canceling transaction \
      -d VERSION=93                                  # API version \
      -d PAYMENTREQUEST_0_CURRENCYCODE=USD \
      -d PAYMENTREQUEST_0_AMT=250                    # total amount of first payment \
      -d PAYMENTREQUEST_0_ITEMAMT=225 \
      -d PAYMENTREQUEST_0_TAXAMT=25 \
      -d PAYMENTREQUEST_0_PAYMENTACTION=Order \
      -d PAYMENTREQUEST_0_DESC=Sunset Sail for Two \
      -d PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID=Receiver_1   # PayPal e-mail of 1st receiver \
      -d PAYMENTREQUEST_0_PAYMENTREQUESTID=CART286-PAYMENT0    # unique ID for 1st payment \
      -d PAYMENTREQUEST_1_CURRENCYCODE=USD \
      -d PAYMENTREQUEST_1_AMT=75                     # total amount of second payment \
      -d PAYMENTREQUEST_1_ITEMAMT=65 \
      -d PAYMENTREQUEST_1_TAXAMT=10 \
      -d PAYMENTREQUEST_1_PAYMENTACTION=Order \
      -d PAYMENTREQUEST_1_DESC=Sunset Wine and Cheese Plate for Two \
      -d PAYMENTREQUEST_1_SELLERPAYPALACCOUNTID=Receiver_2   # PayPal e-mail of 2nd receiver \
      -d PAYMENTREQUEST_1_PAYMENTREQUESTID=CART286-PAYMENT1    # unique ID for 1st payment \
      -d L_PAYMENTREQUEST_0_NAME0=Departs Santa Cruz Harbor Sunday at 3:10 PM \
      -d L_PAYMENTREQUEST_0_NAME1=Returns Santa Cruz Harbor 7:30 PM # begin secondary information \
      -d L_PAYMENTREQUEST_0_NUMBER0=Sunset Sail 22 \
      -d L_PAYMENTREQUEST_0_QTY0=1                   # first ticket \
      -d L_PAYMENTREQUEST_0_QTY1=1                   # second ticket \
      -d L_PAYMENTREQUEST_0_AMT0=125                 # amount of first ticket \
      -d L_PAYMENTREQUEST_0_AMT1=100 \
      -d L_PAYMENTREQUEST_0_TAXAMT0=15               # tax on first ticket \
      -d L_PAYMENTREQUEST_0_TAXAMT1=10 \
      -d L_PAYMENTREQUEST_0_DESC0=An amazing sail on the Monterey Bay. \
      -d L_PAYMENTREQUEST_1_DESC0=Five cheeses, fruit, bread, and Pinot Noir
    

    This request contains both primary and secondary information for each of the two payments. The secondary information for the first payment shows a multi-item purchase—there are two separate sailboat tickets, and the secondary information details the specifics of each. When the buyer authorizes the transaction, they can expand each separate payment to view the secondary information associated with each payment.

    The SetExpressCheckout response includes a token value that you use in the remaining Express Checkout steps.

  2. Use the following URL and the token returned from SetExpressCheckout to redirect the buyer to PayPal so they can authorize the payment:

    https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=TOKEN

    To test this, log into the Sandbox, then issue the redirect command in a browser. You can then log into the PayPal test environment using the credentials from your Personal test account. The above SetExpressCheckout call results in a transaction similar to the following:

    After the buyer authorizes the payment, PayPal returns them to the URL specified in the RETURNURL parameter of your SetExpressCheckout call.

  3. Call GetExpressCheckoutDetails using the token returned from SetExpressCheckout:

    curl https://api-3t.sandbox.paypal.com/nvp \
      -s \
      --insecure \
      -d USER=Caller_ID \
      -d PWD=Caller_Pswd \
      -d SIGNATURE=Caller_Sig \
      -d METHOD=GetExpressCheckoutDetails \
      -d VERSION=93 \
      -d TOKEN=Token                      # TOKEN value returned from SetExpressCheckout
    

    GetExpressCheckoutDetails returns all information associated with the transaction, including the PayerID value that is needed to capture the payment.

  4. Call DoExpressCheckoutPayment to capture the payment:

    curl https://api-3t.sandbox.paypal.com/nvp \
      -s \
      --insecure \
      -d USER=Caller_ID \
      -d PWD=Caller_Pswd \
      -d SIGNATURE=Caller_Sig \
      -d METHOD=DoExpressCheckoutPayment \
      -d VERSION=93 \
      -d TOKEN=Token                                 # TOKEN value returned from SetExpressCheckout \
      -d PAYERID=PayerID                             # PAYERID value returned from GetExpressCheckoutDetails \
      -d PAYMENTREQUEST_0_AMT=250                    # first payment details \
      -d PAYMENTREQUEST_0_CURRENCYCODE=USD \
      -d PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID=Receiver_1 \
      -d PAYMENTREQUEST_0_PAYMENTREQUESTID=CART286-PAYMENT0 \
      -d PAYMENTREQUEST_1_AMT=75                     # second payment details \
      -d PAYMENTREQUEST_1_CURRENCYCODE=USD \
      -d PAYMENTREQUEST_1_SELLERPAYPALACCOUNTID=Receiver_2 \
      -d PAYMENTREQUEST_1_PAYMENTREQUESTID=CART286-PAYMENT1"
    

    This finalizes the transaction. PayPal makes the proper fund transfers and sends an e-mail to the buyer confirming the transaction details.

Learn More

See Implementing Parallel Payments for more details on how to set up parallel payments using Express Checkout.