Quick Start
Step-by-step guide to installing and configuring Split Pay on WooCommerce or FluentCart with any of the three supported Stripe gateway adapters — including Stripe API setup, webhook checks, and connected accounts.
Prefer setup with an AI assistant? Download our Split Pay Setup Skill — a self-contained playbook any AI tool (Claude, ChatGPT, Cursor, etc.) can use to walk you through this configuration interactively, including diagnosis of the most common “why aren’t transfers happening” problems. The Quick Start steps below also work fine on their own.
Required plugins — pick your stack#
Since v3.7.0, Split Pay supports two e-commerce platforms and three Stripe gateway adapters. Pick whichever stack fits your store.
| Stack | Plugins required | Notes |
|---|---|---|
| Stack A — WooCommerce |
WooCommerce (storefront, products, cart, checkout)
+ one Stripe gateway plugin:
+ Split Pay Plugin |
Either Stripe gateway plugin satisfies the requirement; you can also have both installed and Split Pay will register a separate gateway card per gateway on the Integrations tab. |
| Stack B — FluentCart 3.7.0+ |
FluentCart with its built-in Stripe payment module enabled
+ Split Pay Plugin |
Standalone — WooCommerce is not required. See the FluentCart integration page for setup specifics. |
If neither stack is detected, Split Pay still activates — it shows an admin notice and waits until a supported stack is installed before loading the transfer engine.
The step-by-step Quick Start below uses Stack A with the official WooCommerce Stripe Payment Gateway as the worked example. If you’re running Payment Plugins or FluentCart instead, the Split Pay configuration steps are identical — only the gateway-side setup (the section just below) differs. See Integrations Tab for how the per-platform / per-gateway cards work, and the dedicated Payment Plugins and FluentCart pages for stack-specific gateway configuration.
Stripe transfer requirements#
Stripe enforces a few rules on every transfer — failing any of them makes the transfer fail:
- Minimum transfer amount: at least $0.50 USD (or equivalent) per transfer.
- Same country/region: platform and connected accounts must share a country, or fall within Stripe’s US/Canada/UK/EEA/Switzerland cross-border corridor — see International Transfers.
- Sufficient available balance: transfers pull from your platform’s available (settled) balance, not pending funds — see Insufficient balance for transfer if a transfer is rejected.
- Single platform connection: a connected account can belong to only one platform at a time.
For how the money actually moves — platform vs connected accounts, fees, and balances — see How Stripe Transfers Work.
Configuring your Stripe gateway#
Whichever stack you picked, the Stripe gateway plugin needs to be connected to your Stripe platform account before Split Pay can create transfers. Pick the path that matches your stack:
Stack A1 — official WooCommerce Stripe Payment Gateway
The default and most common path. Set up the official WooCommerce Stripe Payment Gateway as follows:
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.
Stack A2 — Payment Plugins for Stripe WooCommerce
If you use Payment Plugins’ woo-stripe-payment instead of (or alongside) the official gateway, the gateway-side setup is similar but lives at WooCommerce → Settings → Payments → Stripe (Payment Plugins). Split Pay detects the Payment Plugins gateway via function_exists( 'stripe_wc' ) and registers a dedicated card for it on the Integrations tab.
Follow the gateway-specific instructions on the Payment Plugins for Stripe WooCommerce integration page, then return here to Configuring Split Pay — the API-key, webhook-check, and connected-account steps are identical.
Stack B — FluentCart built-in Stripe
FluentCart ships its own Stripe payment module — you do not install a separate Stripe plugin. Configure FluentCart’s Stripe module from FluentCart → Settings → Payment Methods → Stripe. Split Pay detects the FluentCart Stripe gateway via the FluentCart\App\Modules\PaymentMethods\StripeGateway\Stripe class.
Follow the platform-specific instructions on the FluentCart integration page, then return here to Configuring Split Pay.
Configuring Split Pay#
Once the Stripe gateway is connected, you need to give Split Pay its own set of API keys and sync your connected accounts. In the WordPress admin sidebar, click the top-level Split Pay menu. The settings page opens on the Integrations tab, which shows a Connected Accounts summary at the top followed by one card per detected platform and Stripe gateway.
Menu moved in v3.7.0. Before 3.7.0 the plugin’s settings page lived under WooCommerce → Settings → Payments → Split Pay. It is now a top-level Split Pay menu, visible regardless of whether your store runs WooCommerce or FluentCart. Direct URL: /wp-admin/admin.php?page=bsd-split-pay-stripe-connect-woo-settings.
Adding your Stripe API keys
Split Pay needs its own secret key (separate from the keys saved in your Stripe gateway plugin) to create transfers and sync connected accounts. You’ll find your secret keys in the Stripe Dashboard → Developers → API keys.
On the Integrations tab, find the card for your Stripe gateway and click its Settings button. The panel expands inline, showing the gateway’s detected key and mode, plus two key slots:
- Test Mode Secret Key — for development and testing. Starts with
sk_test_(orrk_test_for restricted keys). Paste it and click Save Test Key. - Live Mode Secret Key — for processing real payments. Starts with
sk_live_(orrk_live_). Paste it and click Save Live Key.
Each saved slot shows a masked key tail (e.g. sk_test••••M5Ea), and the slot matching the gateway’s current mode gets an ACTIVE badge. You only enter secret keys here — Split Pay reads publishable keys directly from your Stripe gateway plugin, so there is nothing else to paste.
Built-in key validation. Split Pay validates keys on save: secret keys must start with sk_test_, sk_live_, rk_test_, or rk_live_, and each slot only accepts keys for its own mode. 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).
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.
Checking webhooks
After saving your key, click the Check webhooks button on the gateway’s card (next to Settings and Manage Stripe). This is a read-only check: Split Pay counts the active webhook endpoints on that gateway’s key and reports what it finds. It never creates, refreshes, or modifies endpoints.
You don’t need a Stripe webhook for Split Pay to pay your vendors — transfers are order-driven. A webhook (owned by your Stripe gateway plugin) enables automatic dispute and async-failure handling on WooCommerce Stripe, and FluentCart’s own webhook drives refund/dispute reversal and subscription renewals. The check simply confirms webhook delivery is set up for the key.
If the check succeeds, a green message appears next to the button (e.g. “Test: found 1 active webhook endpoint(s)”) matching what you see in your Stripe Dashboard → Developers → Webhooks.
If the check reports an error (or no endpoints), a red message appears in the same spot — the most common causes are listed in the troubleshooting section below.
Syncing connected accounts
Inside the same expanded Settings panel, click Sync Connected Accounts 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. (Clear Synced Accounts removes the locally stored list if you ever need to start fresh.)
Once the sync finishes, the Connected Accounts panel at the top of the Integrations tab shows the synced account count and how many products have transfer rules configured per platform. If you add new connected accounts in the future, click Sync Connected Accounts again to refresh the list.
Webhook check issues#
If the webhook check reports an error — a red message next to the Check webhooks button instead of the green confirmation — check these common causes:
- Wrong mode connection: Make sure your Stripe gateway mode (Test/Live) matches the API keys you entered in Split Pay. The gateway is whichever Stripe plugin you configured above — the official WooCommerce Stripe gateway, Payment Plugins’
woo-stripe-payment, or FluentCart’s built-in Stripe module. If the gateway is in test mode, use test API keys. - Restricted key can’t read webhooks: If the check reports “Restricted key — cannot read webhooks”, your restricted key lacks the Webhooks: Read permission. That only affects the check itself — transfers still work as long as the key has Connect → Transfers: Write. See Adjusting API Key Permissions below.
- No active webhook endpoints found: This isn’t a Split Pay failure — your Stripe gateway plugin owns the webhook endpoint. Reconnect (or re-save) your gateway plugin’s Stripe connection so it recreates its endpoint; the official WooCommerce Stripe gateway creates its endpoint automatically when you connect, and FluentCart has its own webhook setting.
- Inactive restricted key: Stripe automatically limits the access of restricted API keys that have not been used for 180 days. The key isn’t deleted, but API calls start failing. If things were working last quarter and stopped without you changing anything, the key may have been auto-limited — rotate to a new restricted key in the Stripe Dashboard.
- 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.
Do you need a Stripe webhook?#
You don’t need a Stripe webhook for Split Pay to pay your vendors — transfers are order-driven and fire when your store marks the order paid. You do not need to subscribe to any transfer.* events; Split Pay never consumes them. (Versions before 3.8.1 added transfer.created, transfer.reversed, and transfer.updated to your endpoint via a “Sync Webhooks” button — if those events are still on your endpoint they’re harmless, and you can remove them.)
What a webhook is for:
- WooCommerce Stripe: the gateway’s own webhook endpoint (created automatically when you connect the gateway, at a URL like
/?wc-api=wc_stripe) enables Split Pay’s automatic dispute and async-failure handling. - FluentCart: FluentCart’s own Stripe webhook drives refund/dispute reversal and subscription renewals — see the FluentCart integration page.
If the Check webhooks button reports no active endpoints, fix it in your gateway plugin (reconnect its Stripe connection), not in Split Pay.
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-scoped permissions. The restricted key should be configured with at least one Connect permission enabled (Stripe used to surface this as a separate “Connect” badge on the key list; current Dashboard versions show the permission inline when you edit the key). If your key has no Connect permissions, create a new restricted key and tick the Connect category boxes described below.
Edit the API key permissions. Click on the key to edit it.
Enable Connect → Transfers: Write. Under the key’s permissions, find the Connect → Transfers resource and set it to Write. This allows the key to create, update, and reverse transfers. (Older Stripe Dashboard versions labelled this resource Balance Transfers; the underlying API is the same.)
Enable Webhooks: Read (optional). This lets the Check webhooks button list your endpoints; without it the check reports “Restricted key — cannot read webhooks”. Split Pay never creates or modifies webhook endpoints, so no write permission is needed.
Save the key and update it in the gateway’s Settings panel on the Integrations tab. Click Save Test Key or Save Live Key for the matching mode, then re-run “Check webhooks” and “Sync Connected Accounts”.
You’re all set! Once your API keys are saved 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.