How to Make Parallel Payments Using Express Checkout

Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Subscriptions Integration Guide.

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:

  • Parallel payments supports transactions with the payment action SALE. Payment actions AUTHORIZATION and ORDER are not supported.
  • 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.

Create a parallel payment

To make a parallel payment using Express Checkout:

  1. Initiate a SetExpressCheckout request:

    curl https://api-3t.sandbox.paypal.com/nvp \
      -s \
      -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=https://example.com/success.html # URL displayed to buyer after authorizing transaction \
      -d CANCELURL=https://example.com/canceled.html # URL displayed to buyer after canceling transaction \
      -d VERSION=93 # API version \
    
      -d PAYMENTREQUEST_0_CURRENCYCODE=USD # Start primary level information for first payment \
      -d PAYMENTREQUEST_0_AMT=250 \
      -d PAYMENTREQUEST_0_ITEMAMT=225 \
      -d PAYMENTREQUEST_0_TAXAMT=25 \
      -d PAYMENTREQUEST_0_PAYMENTACTION=Sale \
      -d PAYMENTREQUEST_0_DESC=Sandwich Combo \
      -d PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID=Receiver_1 # PayPal e-mail of first receiver \
      -d PAYMENTREQUEST_0_PAYMENTREQUESTID=CART1 # unique ID of first payment – End primary level information for first payment \
      -d L_PAYMENTREQUEST_0_NAME0=Super Sub # Start secondary level information for first payment first item \
      -d L_PAYMENTREQUEST_0_NUMBER0=SS-101 \
      -d L_PAYMENTREQUEST_0_QTY0=1 \
      -d L_PAYMENTREQUEST_0_AMT0=125 \
      -d L_PAYMENTREQUEST_0_TAXAMT0=15 # End secondary level information for first payment first item \
      -d L_PAYMENTREQUEST_0_NAME1=Classic Wine # Start secondary level information for first payment second item \
      -d L_PAYMENTREQUEST_0_QTY1=1 \
      -d L_PAYMENTREQUEST_0_AMT1=100 \
      -d L_PAYMENTREQUEST_0_TAXAMT1=10 # End secondary level information for first payment second item \
    
      -d PAYMENTREQUEST_1_CURRENCYCODE=USD # Start primary level information for second payment \
      -d PAYMENTREQUEST_1_AMT=75 # total amount of second payment \
      -d PAYMENTREQUEST_1_ITEMAMT=65 \
      -d PAYMENTREQUEST_1_TAXAMT=10 \
      -d PAYMENTREQUEST_1_PAYMENTACTION=Sale \
      -d PAYMENTREQUEST_1_DESC=Mocktail Large \
      -d PAYMENTREQUEST_1_SELLERPAYPALACCOUNTID=Receiver_2 # PayPal e-mail of second receiver \
      -d PAYMENTREQUEST_1_PAYMENTREQUESTID=CART2 # unique ID of second payment – End primary level information for secondary payment \
      -d L_PAYMENTREQUEST_1_NAME0=Orange crush # Start secondary level information for secondary payment first item \
      -d L_PAYMENTREQUEST_1_NUMBER0=MC-77 \
      -d L_PAYMENTREQUEST_1_QTY0=1 \
      -d L_PAYMENTREQUEST_1_AMT0=65 \
      -d L_PAYMENTREQUEST_1_TAXAMT0=10 # End secondary level information for second payment first item
    

    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.

    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
    

    Note: 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.

    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_CURRENCYCODE=USD # Start primary level information for first payment \
      -d PAYMENTREQUEST_0_AMT=250 \
      -d PAYMENTREQUEST_0_ITEMAMT=225 \
      -d PAYMENTREQUEST_0_TAXAMT=25 \
      -d PAYMENTREQUEST_0_PAYMENTACTION=Sale \
      -d PAYMENTREQUEST_0_DESC=Sandwich Combo \
      -d PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID=Receiver_1 # PayPal e-mail of first receiver \
      -d PAYMENTREQUEST_0_PAYMENTREQUESTID=CART1 # unique ID of first payment – End primary level information for first payment \
      -d L_PAYMENTREQUEST_0_NAME0=Super Sub # Start secondary level information for first payment first item \
      -d L_PAYMENTREQUEST_0_NUMBER0=SS-101 \
      -d L_PAYMENTREQUEST_0_QTY0=1 \
      -d L_PAYMENTREQUEST_0_AMT0=125 \
      -d L_PAYMENTREQUEST_0_TAXAMT0=15 # End secondary level information for first payment first item \
      -d L_PAYMENTREQUEST_0_NAME1=Classic Wine # Start secondary level information for first payment second item \
      -d L_PAYMENTREQUEST_0_QTY1=1 \
      -d L_PAYMENTREQUEST_0_AMT1=100 \
      -d L_PAYMENTREQUEST_0_TAXAMT1=10 # End secondary level information for first payment second item \
    
      -d PAYMENTREQUEST_1_CURRENCYCODE=USD # Start primary level information for second payment \
      -d PAYMENTREQUEST_1_AMT=75 # total amount of second payment \
      -d PAYMENTREQUEST_1_ITEMAMT=65 \
      -d PAYMENTREQUEST_1_TAXAMT=10 \
      -d PAYMENTREQUEST_1_PAYMENTACTION=Sale \
      -d PAYMENTREQUEST_1_DESC=Mocktail Large \
      -d PAYMENTREQUEST_1_SELLERPAYPALACCOUNTID=Receiver_2 # PayPal e-mail of second receiver \
      -d PAYMENTREQUEST_1_PAYMENTREQUESTID=CART2 # unique ID of second payment – End primary level information for secondary payment \
      -d L_PAYMENTREQUEST_1_NAME0=Orange crush # Start secondary level information for secondary payment first item \
      -d L_PAYMENTREQUEST_1_NUMBER0=MC-77 \
      -d L_PAYMENTREQUEST_1_QTY0=1 \
      -d L_PAYMENTREQUEST_1_AMT0=65 \
    

Learn more

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

Feedback

Have feedback?

Let us know.