Quick Start
Step-by-step guide to installing and configuring the Split Pay Plugin for WooCommerce, including Stripe API setup, webhook syncing, and connected accounts.
Required Plugins#
Split Pay Plugin requires two other plugins to be installed and active on your WordPress site before it can function. All three work together to process payments and create transfers:
| Plugin | Purpose |
|---|---|
| WooCommerce | Provides the storefront, product management, cart, and checkout. This is the foundation for your online store. |
| WooCommerce Stripe Payment Gateway | Connects your store to Stripe so customers can pay with credit cards, Apple Pay, Google Pay, and other methods. This plugin creates the charges on your Stripe account that Split Pay later transfers from. |
| Split Pay Plugin | Listens for successful WooCommerce payments and automatically creates Stripe Transfers from your platform balance to the connected accounts you've configured. |
Install and activate WooCommerce and the Stripe Payment Gateway before installing Split Pay Plugin. Split Pay checks for these dependencies on activation.
Stripe Transfer Requirements#
Before configuring the plugin, make sure you understand Stripe's requirements for transfers. Failing to meet these requirements will cause transfers to fail:
Stripe enforces these rules for all transfers:
- Minimum transfer amount: Each transfer must be at least $0.50 USD (or the equivalent in your currency). Transfers below this amount will fail.
- Same country/region: Your platform and connected accounts must be in the same country or region. Stripe supports cross-border transfers between the US, Canada, UK, EEA, and Switzerland. Outside that corridor, accounts must be in the same country. See International Transfers for details.
- Sufficient pending balance: Your platform's pending Stripe payout balance must have enough funds to cover the transfer. Transfers are created from your pending balance — not your available balance.
- Single platform connection: Each connected account can only be connected to one platform at a time. If an account is already connected to another platform, it must be disconnected first.
Configuring WooCommerce Stripe Payment Gateway#
The WooCommerce Stripe Payment Gateway plugin needs to be connected to your Stripe account before Split Pay can create transfers. Here's how to set it up:
Open the Stripe settings page. In your WordPress admin, navigate to WooCommerce → Settings → Payments → Stripe. You can also go directly to:/wp-admin/admin.php?page=wc-settings&tab=checkout§ion=stripe
Go to the Settings tab within the Stripe payment method configuration.
Connect your Stripe account. Click the "Create or connect an account" button. This will redirect you to Stripe where you'll either sign in to an existing Stripe account or create a new one. Once authorized, you'll be redirected back to your WordPress site.
Verify the webhook endpoint. After connecting, a webhook endpoint is automatically created in your Stripe Dashboard to track payment events between WooCommerce and Stripe.
The WooCommerce Stripe Payment Gateway automatically creates a webhook endpoint when you connect your account. You do not need to manually create one for the Stripe gateway itself.
Configuring the Split Pay Plugin#
Once the Stripe gateway is connected, you need to give Split Pay its own set of API keys and sync your connected accounts. Navigate to WooCommerce → Settings → Payments → Split Pay.
Adding Your Stripe API Keys
Split Pay needs its own API keys (separate from the WooCommerce Stripe gateway) to create transfers and manage webhooks. You'll find your API keys in the Stripe Dashboard → Developers → API keys.
You need keys for each mode you plan to use:
- Test mode keys — for development and testing. These keys start with
pk_test_andsk_test_(orrk_test_for restricted keys). - Live mode keys — for processing real payments. These keys start with
pk_live_andsk_live_(orrk_live_for restricted keys).
Paste both the Publishable key and Secret key (or Restricted key) into the corresponding fields on the Split Pay settings page, then click Save changes.
Built-in key validation. Split Pay validates your API keys on save. Publishable keys must start with pk_test_ or pk_live_. Secret keys must start with sk_test_, sk_live_, or rk_live_. If a key has an invalid format, you'll see an error and it won't be saved. The plugin also displays an admin notice on other WordPress pages if your configuration is incomplete (missing API keys or unsynced webhooks).
Use your platform's API keys — not a connected account's keys. The keys must belong to the Stripe account that receives the initial payment and creates transfers. Using a connected account's keys will cause "No such connected account" errors.
Syncing Webhooks
After saving your API keys, click the "Sync Webhooks" button. This tells Split Pay to create a webhook endpoint on your Stripe account that listens for transfer events (transfer.created, transfer.reversed, transfer.updated).
These webhooks allow the plugin to track the status of transfers and update WooCommerce order notes accordingly.
If the sync succeeds, you'll see a green success message and the webhook endpoint will appear in your Stripe Dashboard → Developers → Webhooks.
If the sync fails, the most common causes are listed in the troubleshooting section below.
Syncing Connected Accounts
Click the "Sync Connected Accounts" button to pull all connected Stripe accounts into the plugin. This fetches the list of accounts connected to your platform so you can select them in transfer rules.
If you add new connected accounts in the future, click this button again to refresh the list.
Webhook Sync Failures#
If the webhook sync fails, check these common causes:
- Wrong mode connection: Make sure your WooCommerce Stripe gateway mode (Test/Live) matches the API keys you entered in Split Pay. If the gateway is in test mode, use test API keys.
- Transfer events not configured: If you're using a restricted API key, it must have permission to access transfer events. See Adjusting API Key Permissions below.
- Incorrect API key permissions: Restricted keys need the Balance Transfers: Write permission at minimum. Keys with read-only access cannot create webhooks or transfers.
- Connected account keys instead of platform keys: You must use API keys from your platform Stripe account — the account that processes the initial payment. Connected account keys won't work.
Updating Transfer Events Manually#
If the automatic webhook sync didn't add the required transfer events, you can add them manually in the Stripe Dashboard:
Open the Stripe Dashboard and go to Developers → Webhooks.
Find the Split Pay webhook endpoint. It will point to your site's URL with a path like /wp-json/split-pay/v1/webhook. Click on it to open the details.
Click "Update details" (or "Edit endpoint") and scroll to the events section.
Add the following events if they aren't already listed:
transfer.createdtransfer.reversedtransfer.updated
Save the webhook endpoint. Transfers will now be tracked in your WooCommerce orders.
Adjusting API Key Permissions#
If you're using restricted API keys (recommended for production), the key must have the correct permissions. Here's what to check:
Go to the Stripe Dashboard → Developers → API keys and find the restricted key you're using.
Verify the Connect badge. The restricted key should show a "Connect" badge, indicating it has access to connected account features. If it doesn't, you'll need to create a new restricted key with Connect permissions enabled.
Edit the API key permissions. Click on the key to edit it.
Enable Balance Transfers: Write. Under the key's permissions, find the Balance → Transfers section and set it to Write. This allows the key to create, update, and reverse transfers.
Enable Webhooks: Write (optional but recommended). This lets Split Pay automatically create and manage its webhook endpoint. Without this, you'll need to create the webhook manually.
Save the key and update it in the Split Pay settings. Click Save changes, then re-run "Sync Webhooks" and "Sync Connected Accounts".
You're all set! Once your API keys are saved, webhooks are synced, and connected accounts are pulled in, you're ready to configure your first transfer rule. Head to the How to Transfer Payments section to learn about global and product-level transfers.