PayPal Marketplace Adaptive Split Payments with Express Checkout

by Drew | Last Updated Nov 11, 2019 | Published on Jan 18, 2018 | Tutorials | 41 comments

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.

Get Our FREE PayPal PHP Class Library

If you are using PHP, everything outlined in this article can be done quickly and easily with our PayPal PHP class library.

More Info

WooCommerce PayPal Split Payments

This step-by-step buide shows you how to use our PayPal WooCommerce plugins to setup a split payment system quickly and easily.

View the Tutorial

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:

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

Call the SetExpressCheckout API with multiple payments included using the PAYMENTREQUEST_n_{parameter_name} fields. The SetExpressCheckout documentation outlines these fields in detail.
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.)
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.

Express Checkout Parallel Payments Demo Kit

Our FREE PayPal PHP Class Library makes it quick and easy to integrate Parallel Payments with Express Checkout. This kit is a fully functional demonstration of integrating Parallel Payments into an actual shopping cart flow.

More Info

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.

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.
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.)
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.

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

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

Express Checkout Billing Agreement Demo Kit

Our FREE PayPal PHP Class Library makes it quick and easy to integrate Billing Agreements with Express Checkout. This kit is a fully functional demonstration of integrating Billing Agreements into an actual shopping cart flow.

More Info

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!

41 Comments

adhik joshi on February 9, 2018 at 12:54 am

any demo for this?

there is tons of examples in your git repo, but is this included?
Reply
- Andrew Angell on February 9, 2018 at 1:51 am
  
  The individual calls to make this whole thing work are included in /templates, but I don’t have a fully functional demo of this particular flow all put together. We could put that together for you for a fee if you’re interested.
  Reply
  - khalid on February 28, 2018 at 11:33 am
    
    could you please put all that together for me! in a .mulib format (MUCOW widget)?
    i’m a Muse CC user
    
    waiting your quote at:
    b-klid@live[dot]com
    
    thank you
    Reply
    - Andrew Angell on March 6, 2018 at 7:35 am
      
      I’m sorry for the delay responding. We could set something up for you. It would be best if you contact us through our quote request form please.
      Reply
Kim yong sung on March 29, 2018 at 3:00 am

Id like to try to find an alternative solution of Paypal adaptive payment system. Could you please recommand a solution in your products?
Thanks in advance.
Reply
- Andrew Angell on March 29, 2018 at 3:39 am
  
  I don’t really have any sort of a turn-key solution. It would all depend on what you’re building into and what the specific goals are. Do you have any specific questions about what was mentioned in this article?
  Reply
Rains on March 30, 2018 at 11:15 am

Hi,

I did test express checkout (sandbox) base on your article and working perfectly. I a bit confusing here about PayPal fees.

1. PayPal charge fee on seller after payment completed by DoExpressCheckoutPayment.php
2. PayPal charge fee again on DoReferenceTransaction.php

Why PayPal charge fee twice?. I thought PayPal only charge fee on the Primary Receiver (Seller) at DoExpressCheckoutPayment.php only.

Need advice. Many Thanks.

Regards,

Rains
Reply
- Andrew Angell on March 31, 2018 at 8:53 am
  
  Yes, with this method there is a fee charged at both spots. That is one disadvantage of this when compared to what Adaptive Payments would offer. However, as mentioned in the article, another option would be using the Payouts API. This would require additional steps to ensure your users have Payouts enabled on their account and you have access to make Payout calls on their behalf, but then the fee would be much cheaper for that secondary payment.
  Reply
  - Rains on March 31, 2018 at 12:59 pm
    
    Today i try to use Payouts API like you say but got an error Fatal error: Class ‘PayPal\Rest\ApiContext’ not found in D:\WampDeveloper\Websites\localhost\webroot\paypal\src\angelleye\PayPal\rest\payouts\PayoutsAPI.php on line 16
    
    Why is this happen?.
    
    My config is correct base on sample.
    
    Regards,
    Rains
    Reply
  - Rains on March 31, 2018 at 1:47 pm
    
    Sorry Andrew,
    
    Now i get it why got an error. That because i missing PayPal SDK on src folder.
    
    Thanks for the great application.
    
    Regards,
    Rains
    Reply
Hayley on April 22, 2018 at 2:28 am

Hi Andrew,

I’m looking for an alternative to paypal adaptive for my site until marketplaces is up and running.

Are you able to email me and provide me a quote for creating the above workflow on my site?
Reply
- Andrew Angell on April 22, 2018 at 4:38 pm
  
  Please submit a quote request here and we can discuss the details with you. Thanks!
  Reply
Gary Funk on May 2, 2018 at 12:55 pm

Hello Andrew,
Is everything you have described here also available in Canada? We are having a Canadian Marketplace site developed and are wanting the ability for Adaptive Chained Payments. We have discovered that Braintree Marketplace is not available in Canada. Thank you. Gary
Reply
- Andrew Angell on May 9, 2018 at 1:13 am
  
  Braintree Marketplaces is actually being deprecated the same as PayPal Adaptive, so I don’t think that’s just a Canada thing. Yes, Express Checkout and all the features mentioned here are available in Canada.
  Reply
Xei on July 20, 2018 at 11:05 pm

Billing agreements seems to only be for subscription plans. They do not allow Payments as and when required. Can you point me to the correct documentation for that? As per PayPal’s current documentation, when I create a billing agreement, I must specify a plan.
Reply
- Andrew Angell on July 25, 2018 at 4:25 pm
  
  You’re looking at the REST API for billing agreements and plans. The Classic API does not work that way. Billing agreements can be used to process future reference transactions as outlined in this article.
  Reply
Jack on August 21, 2018 at 7:01 am

Hello, do you know if this set up using parallel payments will work with digital goods?
Reply
- Andrew Angell on August 22, 2018 at 3:42 pm
  
  Hi Jack,
  
  The actual Digital Goods platform is no longer available. You can use this procedure with any sort of product or service, though, and it will work just fine.
  Reply
Amit on August 27, 2018 at 1:22 am

hello, in the above process when and how the customer is redirected to paypal site for do payment, bcz when we calling setExpressCheckout api then we will receive token. Did not understand the process for customer.
Could you please explain it?
Reply
- Andrew Angell on August 27, 2018 at 11:45 am
  
  The token gets returned by the SetExpressCheckout request/response, and then you redirect the user to PayPal with that token.
  Reply
  - Amit on August 27, 2018 at 11:55 pm
    
    Thanks, Andrew for the response. What would be the URL of Paypal for this?
    One more query is, which method do I used to transfer the amount to vendors and admin in one API call.
    Reply
  - Amit on August 28, 2018 at 12:07 am
    
    Hi Andrew,
    I have used below link to make payment by the customer:
    https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-5GY61557XF1782604
    
    But it not allowing me to login in customer paypal account.
    Is there any requirement for the customer to do payment or account specifics are allowed to do payment.
    Reply
Anand on September 5, 2018 at 9:11 pm

Hello, we are developing an ecommerce platform. We would like the customer payment to go directly to the vendor after deducting our platform fees. We tried speaking with paypal to use their marketplace but it seems they wont let us in since it is in a beta stage. Also it seems paypal adaptive payments parallel payouts is not accepting new users now.
Please suggest the best option for us if we want the vendor to be responsible for disputes, refunds, chargebacks etc and for the payment to go directly to the vendor with only our platform fees coming to us.
Reply
- Andrew Angell on September 6, 2018 at 10:32 pm
  
  Hi Anand,
  
  I really can’t offer any more of the basics than what I outlined in this article. If you have specific questions or concerns about any of this, or if you’re just looking for some additional guidance please submit an order for premium support and we can schedule a time to talk and get your questions answered. Thanks!
  Reply
Dan on October 17, 2018 at 8:18 am

Previously on PayPal Adapative Delayed Chained Payments, you could process the payment, hold it for 90 days with PayPal, and release it when you need too. This is useful because it confirms the user has the funds first, which are released at a later date (useful for a marketplace where a service is being offered, funds added, then released when work is completed). Does your work around offer anything like this?
Reply
- Andrew Angell on October 17, 2018 at 5:34 pm
  
  Yes, that’s exactly the sort of thing you could do with billing agreements and reference transactions…or payouts. The article explains that. 🙂
  Reply
  - Dan on October 23, 2018 at 7:20 am
    
    Okay perfect. Is it possible to get a quote for building this for my site, or do I need to purchase your Premium Support first before a quote can be created?
    Reply
gaurav mehra on December 10, 2018 at 9:00 pm

would all sellers require a business paypal account to use your marketplace? how can you check to make sure that they have a business account before they sign up for your site and start adding items for sale?
Reply
- Andrew Angell on December 10, 2018 at 10:08 pm
  
  Yes, the sellers would need business accounts. If they don’t have a business account the API requests would fail, so you could flag that and send proper notifications accordingly.
  Reply
  - Gaurav Mehra on December 11, 2018 at 11:50 am
    
    how could you verify whether or not a seller has a paypal business account before you allow them to add products for sale on your marketplace?
    Reply
Jacob Moore on December 31, 2018 at 10:12 pm

Greetings Mr. Angell. Is there any solution to for the adaptive payments simple Payment, where the buyer sends payment to me the app owner (for both app-owner commissions and non-commission transactions)? I’ve been using Dokan as a tester/sandbox because it gives the option to hold transactions and have the vendor request withdrawal, but it seems a bit cumbersome. Any ideas? Thanks a bunch!
Reply
- Andrew Angell on January 4, 2019 at 1:13 pm
  
  Adaptive Payments is no longer available for new apps. Do you already have a live APP ID for Adaptive Payments that you’re using with Dokan? If so, then yes, you should be able to use the regular Pay API without issue. Whether or not that’s built into Dokan that way is another story.
  Reply
  - mark on February 18, 2020 at 5:08 pm
    
    Hi Andrew. And thank you for your time
    
    I have a question that is in relation to DOKAN as well.
    
    We have built the website and integrated all of the Supplier’s data, through its system. We then went to take off Sandbox from the Paypal adaptive system and found after 2 weeks of errors that the PayPal adaptive system isn’t available for new builds even through DOKAN still sells it as an option.
    
    We have been told that adaptive Split Payments with Express Checkout may be an option. Was wondering if you know of any other users that have been built with DOKAN and have you come across this issue and if so did they use this option? Would this work as DOKAN doesn’t supply this option out of the box.
    
    Thanks for your time Andrew
    
    Mark
    Reply
    - Drew Angell on February 18, 2020 at 6:05 pm
      
      Unfortunately, those stuck in this situation really don’t have many options. The vendor plugins built on Adaptive Payments don’t seem to be very active in trying to get setup on PayPal’s new platform, so it can definitely be frustrating.
      
      We do have a “PayPal Multi-Account” plugin that lets you create rules to have payments go to different accounts based on order details. It will do Parallel split payments, but not Chained. It uses the regular Express Checkout API so the experience is better than Adaptive.
      
      It’s not tied into Dokan, though. As such, you’d have to manually create a rule for all of your Dokan vendors. We could work with you to create better compatibility, but we’d have to bill that like a custom project. If that’s something you’re interested in please fill out our quote request and we’ll get back to you on that.
      Reply
Nicolaou on January 20, 2019 at 6:05 am

I see that PayPal for Marketplaces is now available (in the UK at least). Would this be a preferable option to Split Payments with Express Checkouts?

https://www.paypal.com/uk/webapps/mpp/partner-marketplaces

I am not a developer and need an easy to understand solution for my Joomla/Quick2cart platform.

Many thanks.
Reply
- Andrew Angell on January 20, 2019 at 7:03 pm
  
  If you can get approved for it that would be the better way to go, but I believe it’s still very limited.
  Reply
John on February 14, 2020 at 8:06 am

Angell- I have got your Billing agreements demo kit working in our test environment.
I see when we do reference transactions, I would be able to charge fee against seller using BAID as Reference ID and credit back to our account. Is there possible to transfer that fee from the seller account to another Payee account using doreference transaction?
Reply
- Drew Angell on February 16, 2020 at 6:28 pm
  
  No, you can’t specify who would pay fees. The other option in this article mentions using Permissions to allow your app to make Payout calls on behalf of others, and that would help you save on fees.
  Reply
KB on October 20, 2020 at 2:37 pm

Hello,

Thanks for the detailed explanation on PayPal Adaptive Chained Payments Using Express Checkout.

It appears that Express Checkout was deprecated in Feb 2017 and PayPal is recommending Checkout your links load an index page – https://developer.paypal.com/docs/nvp-soap-api/.

Do you still recommend your approach? Is it still feasible using Checkout?

Thanks,
KB
Reply
- Drew on October 20, 2020 at 11:00 pm
  
  The new PayPal Commerce Platform would be best to get into now if you’re starting from scratch, but it’s difficult to get fully approved for things there. This approach is still perfectly viable and these APIs are not going away any time soon.
  Reply
  - KB on October 30, 2020 at 12:45 pm
    
    Looked as this and tested it. This is one of the best pieces of content on the web. Thanks for sharing.
    
    Any thoughts or recommendations on building this flow into the In-Context (onsite popup without redirects to PayPal which seems to be designed for the orders API only)?
    Reply