How Stripe Payouts Work

LinkSense uses Stripe Connect to automatically process affiliate payouts. This guide explains how the system works.

Overview

When a customer makes a purchase using an affiliate's referral link or coupon code:

1. Purchase Detection: LinkSense detects the purchase via Stripe webhooks 2. Commission Calculation: The system calculates the commission based on your campaign rules 3. Commission Recording: The commission is recorded in the affiliate's ledger with "pending" status 4. Payout Processing: On a scheduled basis (or manually), pending commissions are paid out to affiliates

Stripe Connect Setup

Before payouts can work, affiliates need to connect their Stripe accounts:

1. Affiliates go to their dashboard → Settings → Payment Method 2. They click Connect Stripe Account 3. They're redirected to Stripe to complete onboarding 4. Once connected, their Stripe account ID is stored in LinkSense

Commission Tracking

Commissions are tracked in real-time:

- One-time Commissions: Recorded when a purchase is completed - Recurring Commissions: Automatically tracked for subscription renewals (if enabled) - Tiered Commissions: Calculated based on affiliate performance metrics

All commissions are stored in the commissions_ledger table with the following statuses:

- Pending: Commission earned but not yet paid out - Paid: Commission has been transferred to affiliate - Cancelled: Commission was cancelled (e.g., due to refund)

Payout Schedule

LinkSense supports two payout methods:

Automatic Payouts

- Runs daily at 2:00 AM UTC - Processes all pending commissions for affiliates with connected Stripe accounts - Minimum payout amount: $10 (configurable)

Manual Payouts

Admins can trigger payouts immediately:

1. Go to Admin → Payouts 2. Click Process Payouts Now 3. All eligible pending commissions are processed

Payout Process

When a payout is initiated:

1. Aggregation: All pending commissions for an affiliate are aggregated 2. Stripe Transfer: A transfer is created via Stripe Connect API 3. Status Update: Commission ledger entries are marked as "paid" with paid_at timestamp 4. Notification: Affiliate receives email and in-app notification

Transfer Details

- Currency: Payouts are made in the currency of the original purchase - Timing: Transfers typically appear in affiliate accounts within 1-3 business days - Fees: Stripe Connect transfer fees apply (see Stripe's pricing)

Handling Refunds

When a refund occurs:

1. LinkSense detects the refund via Stripe webhook 2. A negative commission entry is created (adjustment) 3. If the refund exceeds thresholds, commissions may be put on hold 4. Admins can review and approve/reject holds

See our [Refund Handling Guide](#) for more details.

Troubleshooting

Payout Failed

If a payout fails:

1. Check the affiliate's Stripe Connect account status 2. Verify the affiliate has completed Stripe onboarding 3. Check for account restrictions or holds in Stripe 4. Review error logs in the admin dashboard

Commission Not Recorded

If a commission isn't recorded:

1. Verify the webhook is configured correctly in Stripe 2. Check that the coupon code matches an active affiliate coupon 3. Ensure the campaign is active and within date range 4. Review webhook logs for errors

Best Practices

1. Test First: Always test payouts in Stripe test mode before going live 2. Monitor Regularly: Check payout status daily during initial setup 3. Set Minimums: Configure minimum payout amounts to reduce transaction fees 4. Communicate: Keep affiliates informed about payout schedules and any delays

API Reference

For programmatic payout management, see our [API Documentation](#).