Introduction

PayPal’s Adaptive Payments platform is well known for its ability to create split payments (Chained or Parallel).  This can be useful in cases where you would like to send funds from a single checkout to multiple receiver accounts. 

This is common with vendor websites where you need to take a commission from the vendor selling products on your site, for example.

The Adaptive Payments platform has been officially deprecated, and they are no longer providing Live App IDs necessary to launch a live solution using the Adaptive Payments APIs. 

PayPal is going to be launching a new platform called PayPal for Marketplaces, however, this is not ready yet and there is not any solid information about when exactly it will become available.  

This is leaving many confused and wondering what they’re supposed to do.  The answer is Express Checkout Billing Agreements and Reference Transactions.  The use of the PayPal Payouts API is another potential option.

This article will be a simple outline of the steps necessary to get this done.  I will not be providing specifics of the API requests necessary as that is beyond the scope of this particular article. 

If you would like additional help with that feel free to submit an order for premium support PayPal Help and we can guide you in more depth with one-on-one training.

PayPal Express Checkout

PayPal Express Checkout is a set of APIs that allow you to build PayPal payments into your website or application.  It was originally introduced as an NVP / SOAP API, which are now called Classic APIs.  

PayPal has now introduced a new REST API that supports Express Checkout.  However, this does not fully support the same features that the Classic API does.

To add to the confusion, PayPal has begun to label the Classic APIs as deprecated.  However, they do not require an App ID, and there are so many existing integrations using it that they will not be killing these APIs any time soon.  

We will be discussing the following Classic APIs within this article:

• SetExpressCheckout
• GetExpressCheckoutDetails
• DoExpressCheckoutPayment
• CreateBillingAgreement
• DoReferenceTransaction

PayPal Adaptive Payments

Parallel Payments with Express Checkout

The Adaptive Payments platform consists of Chained Payments and Parallel Payments.  First, we’ll discuss the Parallel Payments functionality because it does not require any additional approval on your account.

The Express Checkout system allows you to specify multiple payments inside a single checkout flow.  Within each of these payments you can specify a SELLERPAYPALACCOUNTID.  This value is set to the email address or the PayPal Merchant ID of the account the funds should be sent to.  Third party merchants do not require any permissions in order to send funds to their account. 

One thing to note is that the buyer will be able to see this split happening during checkout.  If this is a problem you will need to look into the Chained Payments method discussed below.

Steps to Complete an Adaptive Parallel Payment using Express Checkout

1. Call the SetExpressCheckout API with multiple payments included using the PAYMENTREQUEST_n_{parameter_name} fields.  The SetExpressCheckout documentation outlines these fields in detail.
2. When PayPal returns the user to your site you will make a call to GetExpressCheckoutDetails.  This will allow you to obtain the buyer information (ie. Name, Email Address, Shipping Address, Verified Status, etc.)
3. Call the DoExpressCheckoutPayment API to finalize the checkout payment.  This will be very similar to the SetExpressCheckout request and will again include all of the individual payments that will be included on this checkout as outlined in the documentation.

Once you have completed these calls successfully, each receiver included in the SetExpressCheckout and DoExpressCheckoutPayment requests will receive their funds accordingly.

PayPal Adaptive Chained Payments Using Express Checkout

The Chained Payments functionality is what most people tend to use because this hides the split from the buyer. 

This allows you to move the liability for chargebacks / disputes to the primary receiver on the order. 

This functionality is possible using Express Checkout, however, it requires the use of Billing Agreements and Reference Transactions.

Billing Agreements and Reference Transactions

The Express Checkout platform supports the use of Billing Agreements and Reference Transactions.  This allows application developers to process payments on behalf of payers without any future authentication and approval.  The Billing Agreement itself provides the approval for you to process payments on the user’s behalf at any time, and for any amount. 

Because of the freedom and flexibility this gives application developers, there is a strict vetting procedure involved with enabling this on your PayPal account for use.

How to Get Approved for PayPal Express Checkout Reference Transactions

To request that PayPal enable this functionality for you, you will need to call the PayPal support team.  You can find the phone number here.

Let them know that you are calling specifically to enable Reference Transactions on your account for use with Express Checkout. 

Sometimes they will try to steer you in the direction of setting up Subscription buttons or using Recurring Billing profiles.  This is NOT what you want! 

Make sure they understand that what you are seeking is the ability to create Billing Agreements for use with Reference Transactions.

Once you get this feature approved on your account you’ll be ready for the integration.

Steps to Complete an Adaptive Chained Payment Using Express Checkout

In this outline I will use the example of a vendor selling product(s) through your website / application.  Any similar scenario could follow this procedure, though.

Vendor Sign Up

When a vendor creates an account to sell product(s) on your website / application, you will need to create a Billing Agreement via Express Checkout.

1. Make a call to SetExpressCheckout, and be sure to include the Billing Agreement Details parameters outlined in the SetExpressCheckout documentation.  Specifically, you will set L_BILLINGTYPEn to MerchantInitiatedBillingSingleAgreement.
2. When PayPal returns the user to your site, you will make a call to GetExpressCheckoutDetails. This allows you to obtain the buyer information (ie. Name, Email Address, Shipping Address, Verified Status, etc.)
3. Call the CreateBillingAgreement API and store the Billing Agreement ID (BAID) returned in the user profile for this vendor in your system.  Note that this call replaces the DoExpressCheckoutPayment call you would typically use to finalize a payment with Express Checkout.  In cases where you do need to process a payment along with the creation of the billing agreement, then you can go ahead and use DoExpressCheckoutPayment instead of CreateBillingAgreement.  PayPal will still return the BAID in the response.

Customer Checkout

When a customer makes a purchase on your website, you will use the Express Checkout APIs the same way we outlined in the Parallel Payments section above.  However, you will only be including a single payment on the order.

1. Call the SetExpressCheckout API with multiple payments included using the PAYMENTREQUEST_n_{parameter_name} fields.  The SetExpressCheckout documentation outlines these fields. You will use the SELLERPAYPALACCOUNTID field to specify the PayPal email address or Merchant Account ID of the vendor PayPal account so that 100% of the funds will be sent directly to them.
2. When PayPal returns the user to your site, you will make a call to GetExpressCheckoutDetails. This allows you to obtain the buyer information (ie. Name, Email Address, Shipping Address, Verified Status, etc.)
3. Call the DoExpressCheckoutPayment API to finalize the checkout payment.  This will be very similar to the SetExpressCheckout request and will again include the single payment fields with SELLERPAYPALACCOUNTID set to the vendor PayPal account.

At this point the customer will see that their payment is complete to a single seller / receiver.  100% of the funds will have been sent to the vendor PayPal account effectively making them the “primary receiver” of this order.

Collecting Your Commission

You have a couple of options for how to handle this.  You can build this directly into your checkout flow and pull your commissions immediately if you wish. 

However, if your commission is a low dollar amount the PayPal fees might end up being more costly than expected.  In such cases, it may be best for you to maintain a running balance of the commissions owed by your vendor.  You can then trigger the commission payment when it reaches a minimum amount.  For example, $100.00 is a common target.

When you are ready to pull your commissions from the vendor account you will make a call to the DoReferenceTransaction API. 

This request is very simple and includes the amount you would like to process as well as the Billing Agreement ID (BAID) that you obtained for the vendor when they signed up for your site.  Again, you have 2 options for how to handle this:

1. If you prefer to process the commission payments immediately, you can tie the DoReferenceTransaction request into your checkout flow immediately following the successful call to DoExpressCheckoutPayment.  This will give you the same flow that a true Adaptive Chained Payment would provide.
2. If you prefer to keep a running balance, you would update your running balance as part of the checkout flow after the successful call to DoExpressCheckoutPayment.  You can then trigger an automated script (ie. CRON Job) on your server to check the balances for all vendors each day.  Then make the call to DoReferenceTransaction for each one that has reached the minimum payout balance.

Collecting Your Commission – Another Option – PayPal Payouts

Another option you may want to consider for collecting your commission is to trigger Payouts API calls from the account acting as the primary receiver to the account(s) acting as secondary receivers.  This has the advantage of being cheaper on the fees.  The sender pays the fee for a Payout, but the fee is only 25¢.

In this case you would not have the vendor creating a billing agreement as explained above.  Instead, you would have them grant API permissions for your app to make Payout calls on their behalf. 

PayPal will need to enable the Payouts feature on their account before this functionality will work. Using the Permissions API, you could tie the Permissions int the vendor sign-up procedure as well.  Maybe I will write a separate article detailing this option a little more in the future.  Let me know if you’d like to see that.

Conclusion

Whew!  You did it!  I know it may seem like this process involves a lot.  In a way it does, however, once you’ve done it you’ll find that it really is a pretty straight forward procedure.  It’s just a matter of plugging all of the pieces together and then you’ll be set.

The nice thing about this is that you’ll have greater flexibility and freedom to integrate things exactly how you want.  This way it will best suites your needs without any limitations that the Adaptive Payments platform gave. 

The Express Checkout checkout flow is a much better experience for buyers, too, when compared to the Adaptive Payments flow.  As such, this is actually something I have always recommended even before the Adaptive Payments system was officially closed.

Good luck, and happy PayPal-ing!

Other Articles That Might Interest You

• What is PayPal Express Checkout?
• 6 Advantages of PayPal Express Checkout
• How to Build a Real-Time Affiliate System with PayPal Adaptive Payments
• PayPal Smart Payment Buttons – A Better Checkout Experience

Featured PayPal Products and Services