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.
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.
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.
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.
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!
Need Additional Help?
Schedule a live meeting with Drew Angell, PayPal Certified Developer, and get all of your questions or concerns answered.
Featured PayPal Products and Services
-
PayPal Help
$100.00 -
PayPal for WooCommerce
FREE! -
WooCommerce Multiple PayPal Accounts Plugin
$99.99 -
PayPal Shipment Tracking for WooCommerce
$49.99 -
Sale!
PayPal for WooCommerce – Credit Card Split Payment
$99.99$49.99 -
Offers for WooCommerce
$59.99 -
WordPress PayPal Invoice Plugin
FREE! -
WordPress Maintenance
$75.00 on the 1st of each month
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?
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.
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?
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!
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.
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
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.
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.
If you can get approved for it that would be the better way to go, but I believe it’s still very limited.
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?
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.
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
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.
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)?