The following article will give an overview of what is required to build a payment gateway that is compatible with WC Vendors and will support vendor commission payouts. There are requirements that your payment platform will need to meet in order to create a compatible integration. Once you are satisfied that your platform has the required features, there are two parts to building a WC Vendors compatible gateway.
- Platform requirements
- Customer payments
- Vendor payouts
It is possible to create a payouts-only integration however this will not be covered.
Platform requirements
To implement a payment gateway that is compatible with WC Vendors for payments and payouts, your platform will need to be able to support the following features:
- Process payments (including refunds & disputes)
- Split payments or Payout management
Other features that aren’t required but are useful include
- Vendor onboarding
- KYC
- Reports
- Tax management
- Clear documentation for marketplace support
Customer Payments
When building your gateway the first step will be to ensure that you have built a fully compatible WooCommerce payment gateway. This will ensure that customer payments are captured correctly. As this is already covered in detail in the official WooCommerce documentation, we recommend that you read these.
Please be sure to read the developer document available from WooCommerce for this section.
Vendor Payouts
Vendor payouts depend on the kinds of payouts that you support. All of these aspects of how and when to pay vendors are determined by your payment API. The two common scenarios for paying out vendors:
- Split payment
- Scheduled payout
Depending on your platform you will choose one or both of those options for the integration. To understand how to handle vendor payouts you should begin by understanding how our commissions system works internally.
Commission internals
WC Vendors commission system is currently per product based. That means that every product in an order will have its own commission calculated and logged. This may include shipping and taxes.
WC Vendors commissions are only logged when payment has been processed. Once payment has been processed WC Vendors will log the commission in the commissions table. For a commission to be logged the WooCommerce order needs to have either of the two following statuses:
- Processing
- Completed
If the payment gateway is not compatible with WC vendors the commission status is set to due. If the gateway is compatible with WC Vendors and the payout to the vendor is also completed then the commission is set to paid.
Commissions table schema
The commission’s table is where all vendor commissions are logged. Marketplace earnings are currently not logged in this table.
| Column Name | Description |
|---|---|
| id | The unique internal commission id |
| product_id | The product id for the product for the commission |
| order_id | The order id for the commission |
| vendor_id | The quantity of the product |
| total_due | This is the total commission for the product, this does not include tax or shipping |
| qty | The total shipping for the product, must be provide by a compatible shipping plugin |
| total_shipping | The tax for the product, must be provided by a compatible tax solution |
| tax | The tax for the product, this must be provided by a compatible tax solution |
| status | This is the commission status (Paid, Due, Reversed, Refunded) |
| time | The date and time the commission is logged |
WC Vendors classes
When you are developing your integration you will need to access the commission’s table and query relevant information about the vendors, products, and orders. The following classes are the classes most commonly used in payment gateways that support WC Vendors.
| Class name | Description |
|---|---|
| WCV_Commission | This class handles all interactions with the commissions table outlined above. Methods you should use in your gateway: WCV_Commission::set_vendor_product_commission_paid(); to log when a commission has been paid. |
| WCV_Vendors | This class handles methods related to the vendors and their products. Methods that will be used in your payment gateway include: WCV_Vendors::is_vendor( $user_id ); Determine if the user id supplied is a vendor or not. WCV_Vendors::get_vendor_dues_from_order( $order ); get the vendor commissions due for the order. |
Split payments
If your platform supports split payments at the point of sale then you will be implementing the split while processing the payment. This will require that you calculate the commission prior to payment processing.
The split payment between vendors and the marketplace is explained in pseudo-code as follows:
- Capture payment from the customer
- Get the order
- Get the vendor dues from the order
- Iterate over the vendor dues
- Split the dues between each vendor and the marketplace
- Generate a payment to send to the platform
- If successful, set commission status to paid, else error out and leave commission as due
The following code can be used as a guide for your payment gateway integration. This is not complete or intended to be used in production. This is only a guide in the code of the above pseudo-code.
Payouts
The main difference between a payout and a split payment is that the commission has already been calculated and logged. This means that you will only need to query the commission’s table and then update the commission’s table as needed.
Vendor payouts as supported by most payment platforms are managed via a schedule. That schedule could be on the WordPress side or the payment platform side. If you are handling scheduling on the platform and it handles this, you will only need to send the vendor dues to the platform.
How you build your payouts interface within WordPress and WC Vendors is up to you as the developer and platform. We suggest creating settings for the following:
- Schedule (daily, weekly, monthly)
- Minimum payout amounts
- Minimum number of days before a payout can be processed (this can help with regard to refunds or disputes).
A vendor payout is explained in pseudo-code below
- Get the vendor(s) to payout
- Query the commission’s table for all due commissions for the vendors above
- Total the payouts for each vendor
- Process the payout
The above process would be handled on your designated schedule via WordPress. We suggest using the action scheduler that comes with WooCommerce.
WC Vendors Classes
| Class | Description |
|---|---|
| WCV_Vendors | This class handles methods related to the vendors and their products. Methods that will be used in your payment gateway include: WCV_Vendors::is_vendor( $user_id ); Determine if the user id supplied is a vendor or not. WCV_Vendors::get_due_orders_by_vendor( $vendor_id); Get all the due commissions for a particular vendor. |
| WCV_Commission | This class handles all interactions with the commissions table outlined above. Methods you should use in your gateway: WCV_Commission::set_vendor_product_commission_paid(); to log when a commission has been paid. |