Make your Craft ecommerce site into a Marketplace: add payees to products, charge a fee for your platform, and handle payouts automatically via Stripe Connect.
Marketplace Lite for Craft Commerce Lite now available!
- For Craft Commerce Lite
- For Stripe Payment Gateway
- Set Users as Payees on Products
- Charge a flat or percent Fee
- Automatically split payments
To use Marketplace, you will need:
- a Stripe account
- the Craft Commerce plugin installed in Craft CMS
- the Stripe for Craft Commerce payment gateway installed in Craft CMS
To start, install:
- the Marketplace for Craft Commerce plugin
- the OAuth 2.0 Client plugin
You can install the plugins through the Craft CMS dashboard, or using the command line:
# Require Marketplace plugin
composer require kennethormandy/craft-marketplace
# Install OAuth Client plugin
./craft install/plugin oauthclient
# Install Marketplace plugin
./craft install/plugin marketplaceIf you haven’t already, you’ll also need to create a new Stripe Connect application while in Test mode in your Stripe Dashboard.
When you are ready to go to production, you’ll need to do this again with your Stripe Dashboard set to Live mode.
Now, you can configure the OAuth Client plugin to use with your new Stripe Connect settings.
Register a new OAuth App:
| Field | Value | Notes |
|---|---|---|
| Name | Stripe Connect | …or whatever name you’d like |
| Handle | stripeConnect | …or whatever name you’d like |
| Provider | Stripe Connect Express | |
| Client ID | Ex. ca_AaBbCc… | Your Stripe Connect Client ID, from the Stripe Connect settings in the Stripe Dashboard. |
| Client Secret | Ex. sk_AaBbCc… or sk_test_AaBbCc… | Your regular Stripe Secret Key from the Stripe Dashboard. |
You’ll probably want to make your Stripe Connect Client ID and your Stripe Secret Key into environment variables. Then, you can easily switch from Stripe Test keys to Live keys, depending on the environment.
After saving your OAuth App, copy the Redirect URI from the “Setup Info.” You’ll want to add this to your Stripe Connect settings in the Stripe Dashboard. At the time of writing, this is stored in the Stripe Dashboard under: Settings → Connect settings → Integration.
Now, Stripe will be able to redirect sellers on your platform back to Craft CMS after saving their Stripe details.
Now that your OAuth App has been created, you can select it as the app to use, in the Marketplace for Craft Commerce settings. You’ll also need to fill in your Stripe Secret Key here too.
You can also set up a Fee now, or leave it blank. This is described later in Add a Fee
Marketplace contains two new fields for you to use:
- Marketplace Payee, which makes it possible to specify the primary Payee on a given Craft Commerce Product.
- Marketplace Connect Button, gives users a button to connect and review their payout details
You’ll want to create a new Marketplace Payee field, and add it as a new field on the relevant Product Types.
For example, using the Clothing products that come with a fresh Craft Commerce install, you’d add the field to Commerce → System Settings → Product Types → Clothing → Product Fields:
You’ll also want to create a new Marketplace Connect Button field, and add it as a new field for Users. For example:
At this point, everything necessary has been configured. The following example will use the default Craft Commerce products to finish setting up the site with Payees, a fee that the Platform charges, and some optional modifications to the default Craft Commerce Twig templates.
- Add a new user
- Give that user permissions to login to Craft, and to auth with your new Stripe Connect OAuth app
Minimum necessary permissions:
- General Access the control panel
- OAuth Client Login to Apps
- OAuth Client Login to Apps: Login to “Stripe Connect” app (or whatever you called your Stripe Connect app)
Login as that user (When you connect accounts, right now the associated token is always based on the logged in user account, rather than the profile of the person you are looking at. ie. you have to “Login as user” to test connecting their account, and you shouldn’t be able to see this field (or it should be disabled) unless you are looking at your own profile).
- Connect a new account, using Stripe Connect Express
- You should be redirected back to your own Craft CMS application, per Redirect from Stripe to Craft CMS.
Let’s imagine this new user makes one of the Clothing Product we have on our store, and we want them to be paid for it. Now, we can go to that Product, and set them as the Payee:
Marketplace Lite allows you to configure a single flat-rate or percentage fee, inclusive of the customer’s total.
Everything is configured! If you have filled in some content and have:
- The Stripe Payment Gateway in Test mode
- At least one Craft CMS User connected using Stripe, and
- At least one Commerce Product with that user set as a Payee
…you can run through test purchases and see the results in your Stripe dashboard.
Your Craft Commerce templates don’t require any modifications to handle this, but depending on the kind of store or marketplace your are running, you might decide to make some. For example, you might show the Payee to the end cusomter. Imagine “Jane Example” designed “The Last Knee-High” product that comes pre-filled on Craft Commerce, and you want to show them in the default Craft Commerce buy templates:
The templates stored in example-templates in this repository are the minimum changes to use Marketplace with a default Craft Commerce install. The template changes are only to switch from using the Dummy Payment Gateway, from the default install, to Stripe, and to show the customer who the Payee is, which is optional.
As long as you’re using the Stripe Payment Gateway already, none of these changes are required to use Marketplace.
kennethormandy\marketplace\services\PayeesServicePayeesService::EVENT_BEFORE_DETERMINE_PAYEEPayeesService::EVENT_AFTER_DETERMINE_PAYEE
kennethormandy\marketplace\services\FeesServiceFeesService::EVENT_BEFORE_CALCULATE_FEES_AMOUNTFeesService::EVENT_AFTER_CALCULATE_FEES_AMOUNT
use Craft;
use yii\base\Event;
use kennethormandy\marketplace\services\PayeesService;
// …
Event::on(
PayeesService::class,
PayeesService::EVENT_AFTER_DETERMINE_PAYEE,
function (Event $event) {
$lineItem = $event->lineItem;
// Ex. Manually override the Stripe Account ID, based on
// a specific case for your marketplace
$event->gatewayAccountId = "acct_abc123";
Craft::info("Handle EVENT_AFTER_DETERMINE_PAYEE event here", __METHOD__);
}
);Marketplace Lite pairs with Craft Commerce Lite’s single line item orders. If you are using Craft Commerce Pro, and your user interface limits customers to single line item orders (ex. a “Buy now” button with no cart), it will work equally well for you.
Marketplace Lite also includes support for Craft Commerce Pro and orders with multiple line items, when all line items have the same payee.
If you’re interested in more comprehensive payment splitting for items in carts, Marketplace Pro will pair with Craft Commerce Pro, and is in stable beta. Feel free to send me an email if you’re interested in previewing it for your project. It can be installed immediately.