Refund Handling

Automatic refund handling PRO#

Split Pay listens for refund events on whichever platform is processing the order:

• WooCommerce orders — Split Pay hooks into the woocommerce_order_refunded action.
• FluentCart orders — Split Pay hooks into FluentCart’s refund event (see the FluentCart integration page for the exact hook). The reversal logic is identical.

Full refund example#

A $150 order with two transfers:

Order notes created:

• "Split Pay: Reversed transfer tr_xxx to acct_xxx — $45.00 (full reversal)"
• "Split Pay: Reversed transfer tr_yyy to acct_yyy — $30.00 (full reversal)"
• "Split Pay Refund Summary: 2 transfer(s) reversed, 0 failed. Refund ratio: 100%"

Partial refund example#

Same $150 order, but only a $37.50 refund (25%):

Handling failed reversals#

A transfer reversal can fail if the connected account lacks sufficient balance (e.g., the vendor already paid out their funds):

• The failure is logged as an order note with the Stripe error message.
• Other transfers in the same refund continue processing — one failure doesn't block the others.
• The summary note reports the count of successful and failed reversals.

Reclaim shortfalls from future transfers#

By default, a reversal that fails because the vendor's balance is too low is simply logged, and the shortfall sits with you until you reclaim it by hand. Auto refund reclaim closes that gap automatically: when a reversal can't be fully clawed back, Split Pay reverses whatever is available right now and records the rest as outstanding debt for that vendor, then deducts it from their next transfers until the balance reaches zero.

This is an optional feature and is off by default. It is the automatic version of the manual “wait for the balance, then retry” workflow above, and it follows Stripe's own guidance to “reconcile any amount owed back to [the platform] by reducing subsequent transfer amounts.”

Example

A vendor was paid $100 for an order. The customer is refunded in full, but the vendor has already paid out most of their balance — only $50 is available to reverse.

Step	What Split Pay does
Refund issued	Attempts to reverse the full $100.
Balance too low	Reverses the $50 that is available immediately.
Shortfall recorded	Logs $50 as outstanding debt for that vendor.
Vendor's next order ($80 due)	Sends $30 to the vendor and keeps $50 to clear the debt.
Debt cleared	The ledger returns to $0; future transfers are paid in full again.

If a future transfer is smaller than the outstanding debt, the entire transfer is withheld and the remaining balance carries over to the one after that. Each deduction is recorded as an order note so there's always a paper trail.

Enabling it

Go to Split Pay → Global Transfer Settings and tick “Reclaim refund shortfalls from a vendor's future transfers.”

Seeing what each vendor owes

Outstanding balances appear on the Split Pay → Platform Status tab, broken down per connected account, Stripe mode, and currency, along with how much has been recovered so far. If a vendor has left your store and will never receive another transfer, use Mark cleared to write the balance off — this only updates the ledger, it never moves money.

How it stays safe

• Per currency and per Stripe mode — a USD debt is only ever recovered from USD transfers, and a test-mode debt never affects live payouts (and vice-versa).
• Never over-charges a vendor — debt is reserved atomically before each transfer, so two orders processed at the same time can't both claw back the same balance.
• Idempotent — a refund that fires twice (for example a manual refund plus a webhook) records the shortfall only once, and a transfer that's retried never double-deducts.
• Accurate refunds afterwards — the transfer log stores the net amount the vendor actually received, so refunding a debt-reduced order reverses exactly what was paid out, never more.
• Forward-only — turning the feature on doesn't retroactively create debt for refunds that already failed; it applies from the moment it's enabled. Turning it back off pauses recovery and leaves existing balances visible on the Status tab.

Developer note: the amount withheld from any single transfer can be capped with the spp_debt_recovery_max_fraction filter (default 1.0, i.e. up to 100% of each transfer).

Requirements for automatic reversals#

• Split Pay PRO — Automatic refund handling requires the PRO version.
• Transfer log entries — The plugin reverses transfers recorded in its transfer log. Orders placed before installation won't have log entries and must be reversed manually.
• Same currency — Reversals must be in the same currency as the original transfer. This is a Stripe platform rule, not a Split Pay limitation: a reversal can only return funds in the original transfer’s currency — Stripe doesn’t convert at reversal time. See Stripe’s Transfer Reversals API reference.
• Connected account balance — Vendors must have sufficient Stripe balance to cover the reversal amount.
• Refund issued through your store admin, not directly in Stripe — This applies to both WooCommerce and FluentCart. A refund initiated directly in the Stripe Dashboard bypasses the platform refund event Split Pay listens for. See the FluentCart-specific refund-handling note for details on Stack B’s refund event.

---

Manual reversals via Stripe Dashboard#

You can reverse transfers manually through the Stripe Dashboard — useful for free version users, orders placed before the plugin was installed, or edge cases the automatic process doesn't cover.

Reversals via the Stripe API#

You can also reverse transfers programmatically using the Stripe Transfer Reversals API. Don’t hard-code your secret key — load it from an environment variable, a secret manager, or your hosting platform’s config so it never reaches version control:

// Load your platform secret key from the environment, NOT a literal.
// It will start with sk_test_ in test mode or sk_live_ in live mode,
// or rk_test_ / rk_live_ if you are using a restricted key with
// "Connect → Transfers: Write".
$stripe = new \Stripe\StripeClient(getenv('STRIPE_SECRET_KEY'));

// Reverse the full transfer
$reversal = $stripe->transfers->createReversal(
    'tr_TRANSFER_ID',
    []
);

// Partial reversal
$reversal = $stripe->transfers->createReversal(
    'tr_TRANSFER_ID',
    ['amount' => 1000] // $10.00 in cents
);

---

Retrying failed transfers#

If transfers fail during initial processing (e.g., network issues or temporary Stripe errors), you can retry them directly from the order page. See Retry Failed Transfers for details.

Technical implementation#

For developers and store owners who want to understand the internals:

• WordPress hook: woocommerce_order_refunded (priority 10, receives $order_id and $refund_id)
• Refund ratio calculation: refund_amount / order_total
• Stripe API: Uses $stripe->transfers->createReversal() — full amount when ratio is 100%, calculated amount for partial refunds
• Transfer lookup: Queries the bsd_scsp_transfer_log database table for all successful transfers matching the order ID
• Error isolation: Each reversal is wrapped in its own try/catch block so individual failures don't prevent other reversals