Payouts

Overview

Payouts are batch payments to partners that cover one or more approved commissions. The provider controls when payouts are generated and how partners are paid.

Payout lifecycle

Commissions approved
        │
        ▼
Generate payouts (by date range)
        │
        ▼
Payout created (status: pending)
        │
        ├── Pay via Stripe Connect → status: paid
        ├── Mark as paid manually  → status: paid
        └── Cancel                 → status: cancelled

Status values

Generating payouts

Providers generate payouts by specifying a date range. Affihub sums all approved commissions for each partner within that period:

curl -X POST "https://api.affihub.com/api/v1/payouts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period_start": "2026-03-01",
    "period_end": "2026-03-31"
  }'

This will:

1. Query all approved commissions in the date range, grouped by partner
2. Skip partners whose total is below the program's min_payout_cents threshold
3. Create a payout record for each qualifying partner
4. Update the related commissions to processing status

Dry run

Preview what payouts would be generated without creating them:

curl -X POST "https://api.affihub.com/api/v1/payouts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period_start": "2026-03-01",
    "period_end": "2026-03-31",
    "dry_run": true
  }'

Minimum payout threshold

Programs can set a minimum payout amount (min_payout_cents). Partners whose approved commissions total less than this amount will not receive a payout in that period — their commissions roll over to the next cycle.

Set via the API:

curl -X PATCH "https://api.affihub.com/api/v1/programs/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"min_payout_cents": 5000}'

This sets a $50.00 minimum.

Payout methods

Partners configure their preferred payout method in their portal settings:

Stripe Connect payouts

For Stripe Connect, Affihub can execute the transfer automatically:

curl -X POST "https://api.affihub.com/api/v1/payouts/pay_abc123/pay" \
  -H "Authorization: Bearer YOUR_API_KEY"

This creates a Stripe Transfer to the partner's connected account. The partner must have completed Stripe Connect onboarding (see below).

Manual payouts

For PayPal, bank transfer, or crypto, you pay the partner outside of Affihub and then mark the payout as paid:

curl -X PATCH "https://api.affihub.com/api/v1/payouts/pay_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid", "payout_ref": "paypal-txn-123"}'

Stripe Connect onboarding

Partners who want direct bank payouts can onboard via Stripe Connect:

1. Partner clicks "Connect Stripe" in their portal
2. Affihub creates a Stripe Express account and generates an onboarding link
3. Partner completes Stripe's identity verification and bank account setup
4. Once verified, their stripe_account_id is stored and payouts can be executed automatically

Partners can check their Stripe Connect status in their portal under Settings.

Partner-requested payouts

Partners can request payouts from their portal if their approved commission balance meets the minimum threshold:

1. Partner goes to Payouts in their portal
2. Clicks Request Payout
3. A payout with status requested is created
4. The provider reviews and either approves (pays) or cancels it

Payout term

Programs can configure a payout_term (e.g., NET-15, NET-30) that defines the payment schedule. This is informational — it sets expectations but doesn't automatically trigger payouts.

When commissions become "paid"

When a payout status changes to paid:

• All commissions included in that payout are updated to paid status
• The paid_at timestamp is set on the payout
• A payout.paid webhook event is fired