---
name: split-pay-setup
description: Use this skill any time the user is configuring the Split Pay WordPress plugin (Stripe Connect for WooCommerce or FluentCart). It walks through Stripe Connect prerequisites, the Split Pay Integrations tab configuration, syncing webhooks for transfer events, onboarding vendor accounts, and verifying with a real test transaction. Triggers on phrases like "set up Split Pay", "configure Split Pay", "connect Stripe to Split Pay", "Split Pay transfers not working", "Split Pay says cannot access connected accounts", "split payments WooCommerce", "vendor payouts WordPress", or any mention of Split Pay alongside Stripe, Connect, WooCommerce, FluentCart, transfers, vendors, or platform account. Use proactively even when the user doesn't name the skill — if their site uses Split Pay and they're stuck on setup or transfers, this is the playbook.
metadata:
  version: "1.0.0"
  homepage: "https://docs.splitpayplugin.com"
  source: "https://docs.splitpayplugin.com/assets/skill/"
license: MIT
---

# Split Pay Setup Assistant

> **About this file:** these are instructions for an AI assistant helping
> a Split Pay PRO customer set up the plugin. The customer ("the user")
> is referred to in the third person here so the AI knows its role —
> when actually talking to the user, the AI addresses them as "you".
> Customers reading this directly: mentally translate "the user" as
> "me" and you'll follow along fine.

You help a Split Pay PRO customer get from "installed" to "first successful
test transfer" — and diagnose the common reasons it isn't working yet.

Split Pay sits on top of an underlying Stripe payment gateway (WooCommerce
Stripe Payment Gateway, Payment Plugins for Stripe, or FluentCart Stripe)
and uses **Stripe Connect** to split each order's revenue between the
user's Stripe account (the "Platform") and one or more **connected vendor
accounts**.

A working setup means three things agree:

1. The **underlying Stripe gateway** is connected to the user's Platform
   Stripe account (in the mode the user wants — test or live).
2. The **Split Pay Integrations tab** has Platform API keys for that **same
   account** in **matching modes**.
3. The Platform Stripe account has **Stripe Connect enabled**, **webhooks
   subscribed to `transfer.*` events**, and **at least one connected vendor
   account**.

If any of those is off, transfers don't happen. This skill walks them in
order.

## When this skill fires

Use it whenever the user is configuring Split Pay or troubleshooting why
transfers aren't going through. Concrete triggers:

- "I just bought Split Pay PRO, how do I set it up?"
- "Transfers aren't appearing in the Transfers tab"
- "Split Pay says 'cannot access the connected accounts of your platform'"
- "I'm trying to connect Split Pay to my Stripe account and it's not working"
- "How do I add a vendor to Split Pay?"
- "Test transactions aren't producing transfers"
- "I have WooCommerce Stripe set up, what do I do in Split Pay?"

You don't need the user to name the skill or quote any of these — if
they're configuring or debugging Split Pay, you're in the right place.

## Phase 1 — Prerequisites (verify before touching the plugin)

Before opening the Split Pay settings, confirm with the user:

- **A Stripe account they own directly.** Accounts created by clicking
  "Connect to Stripe" inside WooCommerce.com (where the Stripe Dashboard
  shows `woocommerce.com` under their business name) **cannot** be a Split
  Pay Platform. If they have one of those, they need to either complete
  Stripe Connect on their own (non-WooCommerce) account, or create a brand
  new Stripe account at stripe.com that they own directly.
- **Stripe Connect enabled** on that account. Send them to
  `https://dashboard.stripe.com/<acct_…>/connect/overview` (substituting
  their account ID). If they see "Get started", they haven't completed
  Connect onboarding yet — that has to happen first (typically choose
  Standard platform, pick a platform name + branding, save).
- **A supported gateway plugin installed and connected** to that same
  Stripe account, in the same mode they want to use:
  - WooCommerce Stripe Payment Gateway (free, official)
  - Payment Plugins for Stripe WooCommerce
  - FluentCart's built-in Stripe module (if using FluentCart instead of
    WooCommerce)
- **The gateway connection must be done independently in test mode AND
  live mode.** Most users only complete the live one because that's what
  onboarding prompts. To run test transactions they also need a test
  connection (same account; Stripe shows it once per mode).
- **Split Pay PRO activated.** The free version doesn't support transfers.

## Phase 2 — Audit current state

Direct the user to **wp-admin → Split Pay → Integrations**:

```
/wp-admin/admin.php?page=bsd-split-pay-stripe-connect-woo-settings&tab=integrations
```

Have them capture:

- **Any red admin notice at top of the page.** The most common is *"Split
  Pay … : You cannot access the connected accounts of your platform's
  connected accounts."* If you see this, jump to Phase 3 → "Connect not
  enabled" or "Wrong account in slot."
- **Connected Accounts panel** at top: count of synced Stripe accounts,
  per-integration product counts. "0 synced" is normal at the start.
- **Per-integration cards**, one for each gateway they have installed:
  - Status (Active / Not Installed / Not Found)
  - Mode (Test / Live)
  - API Key tail (`••••xxxx`) — this is the gateway's own publishable key,
    NOT Split Pay's stored Platform key
- **Click "Settings" on each Active gateway card.** It expands an inline
  panel showing:
  - Test Mode Secret Key tail (what Split Pay has saved for test mode)
  - Live Mode Secret Key tail (what Split Pay has saved for live mode,
    with an "ACTIVE" badge)
  - Buttons: "Sync Connected Accounts", "Sync Webhooks", "Clear Synced
    Accounts"

### Cross-verify the Platform acct ID — without leaving wp-admin

The user can confirm which Stripe account their gateway is actually
connected to (the source of truth for what should be in Split Pay's
slots) without opening the Stripe Dashboard:

**WooCommerce → Settings → Payments → Stripe → Settings tab → Account
details panel.**

That panel shows the connected `acct_…` ID, the business name and email
on the account, and Payment / Payout / Webhook / Sync status badges per
mode. Whatever `acct_…` shows there is the same account the Split Pay
Platform keys MUST come from.

## Phase 3 — Diagnose

Match observed state to the patterns below, in order. The first match is
usually the right diagnosis; sometimes two layer (e.g., wrong-mode key
*and* Connect not enabled). Fix in this order: Connect first → keys → sync
connected accounts → sync webhooks → test.

### 3.1 Wrong-mode key in a slot

**Symptom**: The masked tail above the input box starts with `sk_live_…`
or `rk_live_…` but the heading says "Test Mode Secret Key" — or the
opposite. Customers paste from Stripe in muscle-memory order without
noticing the mode toggle.

**Fix**:
1. In the Stripe Dashboard, toggle to the correct mode (top-left).
2. Developers → API keys → reveal/copy a Standard Secret (`sk_test_…` or
   `sk_live_…`).
3. Paste into the correct Split Pay slot. Click the per-slot Save button.
4. The plugin re-renders the slot with a new tail. Confirm it took.

### 3.2 WooCommerce.com-issued Stripe account

**Symptom**: Stripe Dashboard shows `woocommerce.com` under the business
name in the top-left. Connect cannot be enabled on these.

**Fix**: They need to use a different account.
- If they have their own (non-WooCommerce) Stripe account, finish Connect
  on it and switch their gateway to use it.
- Otherwise, create a fresh Stripe account at stripe.com that they own
  directly, complete identity verification, enable Connect, then connect
  their gateway to it.

### 3.3 Connect not enabled

**Symptom**: acct ID is correct, key prefix matches the slot, but the red
"cannot access connected accounts" notice persists. (You can confirm via
API: `curl https://api.stripe.com/v1/accounts -u <sk_key>:` returns
`data: []` or a parameter error.)

**Fix**: Direct them to
`https://dashboard.stripe.com/<acct_…>/connect/overview` and walk them
through Connect onboarding (pick Standard, set platform name + branding,
save). Once done, sometimes Stripe rotates the secret — have them re-copy
the key and re-paste into Split Pay.

### 3.4 Gateway has no test connection

**Symptom**: They want to run a test transaction. WooCommerce → Stripe →
Account Details only shows a live connection (test side is blank, or
"Enable test mode" is unchecked).

**Fix**:
1. WooCommerce → Stripe → Settings → check "Enable test mode" → page
   reloads.
2. Click "Configure connection". Walk through the Stripe OAuth flow while
   logged into Stripe in test mode (same account).
3. Account Details now shows the test acct ID (same as live).
4. In Split Pay, paste a `sk_test_…` into the Test slot.

Note: enabling test mode on the gateway makes the live storefront use test
payment methods. If the site has live traffic, do this in a maintenance
window or revert test mode after the test transaction.

### 3.5 Zero connected vendor accounts

**Symptom**: Connected Accounts panel shows "0 synced Stripe accounts"
even though keys/Connect/webhooks all check out.

**Fix**:
- If vendors already exist on the Stripe side (visible at
  `https://dashboard.stripe.com/<acct>/connect/accounts`): click "Sync
  Connected Accounts" on the gateway card. Split Pay pulls them in.
- If no vendors exist yet: use Split Pay → Vendor Onboarding to generate a
  Connect onboarding URL. Share with each vendor; they complete a short
  Stripe Express form. Once at least one vendor exists, click Sync.

### 3.6 Webhooks missing

**Symptom**: Test charge succeeds but Transfers tab stays empty. Stripe
Dashboard → Webhooks → recent deliveries shows no `transfer.created`.

**Fix**: Click "Sync Webhooks" on the gateway card. Split Pay POSTs to the
Stripe API and creates an endpoint subscribed to `transfer.created`,
`transfer.updated`, `transfer.reversed`. If sync errors, the saved key
lacks the right scopes (see 3.7).

### 3.7 Wrong-scope Restricted Key

**Symptom**: Saved key starts with `rk_`. Various silent failures: Sync
Connected Accounts returns empty, Sync Webhooks 403s, transfers fail with
"permission" errors.

**Fix**: Either re-issue the Restricted Key with all the scopes listed in
the "Stripe Keys" section below, or just use a Standard Secret Key (`sk_…`)
which has full account scope. Standard keys are the right tradeoff during
setup; they can be swapped for Restricted Keys later once everything works.

### 3.8 Empty Vendor Onboarding tab

**Symptom**: Navigating to the Vendor Onboarding tab shows the tab strip
but no body content.

**Fix**: This is a UX gap — the tab hides its body when the platform
connection isn't functional. It populates once Phases 3.1–3.4 are done.

## Phase 4 — Verify with a test transaction

Once all of:
- Underlying gateway in test mode, connected to the right acct
- Split Pay Test Mode Secret Key set (`sk_test_…` from the right acct)
- Connect enabled
- At least 1 connected vendor synced
- At least 1 product assigned to that vendor (via Split Pay → Global
  Transfer Settings → Connected Stripe Account dropdown, or via a
  specific product's Split Pay metabox)
- Webhook endpoint exists with `transfer.created` event

…run the test:

1. Buy one of the assigned product through normal storefront checkout.
2. Pay with test card `4242 4242 4242 4242`, any future expiry, any CVC,
   any postal.
3. Confirm WooCommerce order shows "Processing" or "Completed" with a
   `pi_test_…` PaymentIntent in the order notes.
4. Within 30 seconds, Split Pay → Transfers shows a row with the order
   ID, vendor acct, transfer amount, and a `tr_test_…` Stripe Transfer
   ID populated.
5. Stripe Dashboard → Webhooks → recent deliveries shows
   `transfer.created` with HTTP 200.

If all four happen, the setup is working. Repeat the test in live mode
(real card, small amount) to confirm live transfers flow before promoting
to real customers.

### Test card cheat sheet

| Card | Purpose |
|---|---|
| `4242 4242 4242 4242` | Succeeds, no auth. Default happy-path test. |
| `4000 0027 6000 3184` | Triggers 3D Secure. Confirms SCA doesn't break transfers. |
| `4000 0000 0000 9995` | Declines `insufficient_funds`. Tests failed-charge handling. |
| `4000 0000 0000 0259` | Triggers a dispute. Useful for refund-related setup. |

Full list: https://docs.stripe.com/testing#cards

### Failure modes when the test transfer doesn't appear

| Symptom | Likely cause |
|---|---|
| Checkout itself fails | Gateway test mode misconfigured — re-do "Configure connection" in test mode |
| Order completes, no Transfers row | Vendor not assigned, OR "Delay transfers until Completed" checkbox is on while order is still "Processing" |
| Transfers row appears but `tr_…` is blank | Stripe rejected the `/v1/transfers` POST — check wp-admin error log + Stripe Dashboard → Logs filtered to `POST /v1/transfers` |
| `tr_…` exists but webhook never fires | Webhook endpoint missing or returning non-2xx — re-Sync Webhooks |
| Transfer fails `insufficient_funds` | Platform test balance is empty — top up at Stripe Dashboard → Test data → Add funds, or accept that test transfers don't move money on the Stripe ledger |
| `permission_denied` on transfer | Saved key lacks Transfer:Write scope — re-issue with right scopes |

## Stripe Keys reference

### Key types in Split Pay's Settings panel

The Settings panel on each gateway card has Test Mode Secret Key and Live
Mode Secret Key fields. Both want a Platform Account secret —
`sk_*` or `rk_*` from the user's Platform Stripe account (not from a
connected vendor account, not from a WooCommerce.com-issued account).

| Slot | Acceptable | Not acceptable |
|---|---|---|
| Test Mode Secret Key | `sk_test_…`, `rk_test_…` | Any `…_live_…` key |
| Live Mode Secret Key | `sk_live_…`, `rk_live_…` | Any `…_test_…` key |

### Required Restricted-key scopes

If using a Restricted Key (`rk_*`), enable all of:

- Charges: Read
- Customers: Read
- Refunds: Read
- Connect → Connected Accounts: Read + Write
- Connect → Transfers: Read + Write
- Connect → Application Fees: Read
- Webhooks → Webhook Endpoints: Read + Write
- Webhooks → Events: Read
- Stripe Connect → Account Links: Write (if onboarding vendors via
  Express/Standard)

If unsure or starting out, just use a Standard Secret Key (`sk_…`) — full
account scope, "just works", swap to Restricted later.

## URL map for the user's reference

| Surface | URL pattern |
|---|---|
| Split Pay Integrations tab | `/wp-admin/admin.php?page=bsd-split-pay-stripe-connect-woo-settings&tab=integrations` |
| Split Pay Global Transfer Settings | `…?tab=main` |
| Split Pay Transfers (ledger) | `…?tab=transfers` |
| Split Pay Bulk Editor | `…?tab=bulk_editor` |
| Split Pay Vendor Onboarding | `…?tab=vendor_onboarding` |
| WC Stripe Account Details (acct ID source of truth) | `/wp-admin/admin.php?page=wc-settings&tab=checkout&section=stripe&panel=settings` |
| Stripe Dashboard (substitute acct ID) | `https://dashboard.stripe.com/<acct_…>/dashboard` |
| Stripe Connect overview (enable Connect here) | `https://dashboard.stripe.com/<acct_…>/connect/overview` |
| Stripe API keys | `https://dashboard.stripe.com/<acct_…>/apikeys` |
| Stripe Webhooks | `https://dashboard.stripe.com/<acct_…>/webhooks` |
| Stripe Connected accounts list | `https://dashboard.stripe.com/<acct_…>/connect/accounts` |
| Test-mode versions of any Stripe URL | insert `/test/` after the acct ID, e.g. `…/<acct_…>/test/apikeys` |

## What this skill does NOT cover

- WordPress / hosting / theme / non-Split-Pay plugin issues
- Refunds (do those via Stripe Dashboard or your gateway's order page —
  Split Pay's [Refund Handling](https://docs.splitpayplugin.com/features/refund-handling/)
  page covers the policy)
- Vendor KYC / identity-verification failures (those are between the
  vendor and Stripe — vendors contact Stripe support directly)
- Custom code, filters, programmatic transfer adjustments — see
  [Developer Filters](https://docs.splitpayplugin.com/features/developer-filters/)

## When to ask for human help

If you've gone through Phases 1–4 and the test transfer still doesn't go
through, email **support@gauchoplugins.com** with:

- Site URL
- Screenshot of the Integrations tab with the failing gateway card's
  Settings panel expanded
- Screenshot of WooCommerce → Stripe → Account Details panel
- Exact text of any red error notice in wp-admin
- Stripe Dashboard → Logs filtered to recent `POST /v1/transfers` or
  `POST /v1/webhook_endpoints` calls (screenshot or copied JSON)

For hands-on help, include:
- A temporary wp-admin login URL (use the
  [Temporary Login Without Password](https://wordpress.org/plugins/temporary-login-without-password/)
  plugin)
- A Stripe team invite for `support@gauchoplugins.com` as Super Admin on
  your Platform account (Stripe Dashboard → Settings → Team)

Full docs: https://docs.splitpayplugin.com