> For the complete documentation index, see [llms.txt](https://docs.wandreferrals.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wandreferrals.com/payouts-and-tax-production-rollout-gate-pending/payout-methods-and-batches.md).

# Payout methods and batches

> **Production status:** The live-payout rollout is not approved, and the repository does not yet enforce a universal server-side payout kill switch. The workflow below documents implemented interfaces for authorized non-production validation. Do not create a production batch, call a payout provider, or mark a real obligation paid. Launch requires the server-side gate, verified denial evidence, review, and separate rollout approval.

## What it does

The **Payouts** page is where you pay affiliates the commissions they've earned. You assemble approved payable commissions into a **batch**, then pay it out — manually or through an automatic payout provider.

## Payout methods

Wand Referrals supports these payout methods (availability depends on your plan and configuration in **Settings → Payments/Integrations**):

| Method                               | Notes                                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| **PayPal**                           | Automatic payouts via the PayPal Payouts API (Professional plan)                                        |
| **Shopify store credit / gift card** | Issued as store credit / gift cards (Growth plan+)                                                      |
| **Stripe Connect**                   | Provider adapter only; unavailable to merchants because connected-account onboarding is not implemented |
| **Bank transfer**                    | Manual out-of-band payment recorded with **Mark as paid**                                               |

> The interactive Payouts screen supports one-click **PayPal** and **store credit** actions; bank transfer and other methods (check, Venmo, etc.) are handled manually. A guarded Wise adapter exists, but its token/profile are provider-managed, merchant Settings has no Wise credential fields, and no interactive payout action invokes it. Wise automatic payouts are therefore unavailable. A guarded Stripe transfer adapter also exists for provider-managed test data, but neither merchant settings nor the affiliate portal can create the required connected-account id. Stripe payouts are unavailable and must not be selected or attempted.

## Creating & paying a batch after rollout approval

1. Open **Payouts**.
2. **Create batch** for a date range — it collects **payable, eligible, un-batched** commissions (plus grandfathered mature compatibility rows) that meet the canonical program → store → $25 threshold.
3. Review the batch total and affiliate breakdown.
4. Pay it:
   * **Pay via PayPal** or **Issue store credit** for the supported automatic providers, or
   * **Mark as paid** to record an out-of-band payment you made yourself. Before confirming, send the net amount after any displayed clawback and required tax withholding, not the gross commission total. The confirmation applies the same accounting as provider payouts and blocks capped or partially settled batches rather than guessing.
5. You can **void** an open batch only before any provider settlement has started. A mixed-provider batch that returns to Open after partial settlement keeps its durable settlement history and cannot be voided or manually finalized; continue it through the original provider action.

Batch statuses are **Open → Processing → Paid**. Marking a batch paid also marks each commission in it and each payout item **Paid**. The manual path records clawback and tax-withholding deductions atomically and notifies each affiliate once with the net amount. Automated providers also maintain a per-affiliate settlement record with a stable payment key, attempt count, provider reference, and durable outcome.

## The max-payout guard

Every payout path enforces each program's **maximum payout limit**. If paying a batch would push an affiliate over a capped program's limit (already-paid + this batch), the payout is blocked with a clear message. Remove those commissions or raise the cap. See [Commission base](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/programs/commission-base/README.md).

## Failures & transparency

If a provider definitely rejects a payout before success, the payout item records a categorized reason and time so you can fix it and retry. The retry uses the original payment key rather than creating a new obligation.

If a PayPal outcome is pending or unknown—for example, a timeout after submission or a local commit failure after provider success—the batch remains in **Processing** and the affected item shows **Payout reconciliation required**. Do not void, mark paid, or issue another payment. An authorized merchant can use **Check PayPal status**: Wand queries only the exact stored PayPal batch reference, follows a bounded result set, and commits only exact terminal sender-item outcomes. Successful items settle, terminal failures are durably recorded and return the batch to Open for corrective handling, and missing, held, unclaimed, or otherwise nonterminal items remain claimed. If current clawback or withholding accounting no longer equals the immutable submitted net, the check fails closed for operator review. Preserve provider evidence and never place credentials, recipient details, or gift-card values in support notes.

## Invoices

Generate a printable **payout invoice** per batch (Print / Save as PDF), with EU-invoice formatting if configured. You can also export all invoices for paid batches at once.

## Related

* [Thresholds & automatic payouts](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/payouts/thresholds-and-auto-payout/README.md)
* [Tax forms & withholding](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/payouts/tax-forms/README.md)
* [Clawback — reclaim or waive paid commissions](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/reversals/clawback/README.md)
* [Billing plans](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/account/billing-plans/README.md)