Stripe Integration

​

Overview

• Accept payments for auction wins
• Process pre-order charges for queue and draw winners
• Manage subscription billing for Fanfare itself
• Split payments between the platform and connected accounts

​

Prerequisites

• A Stripe account (Standard or Express Connect account)
• Stripe account must have charges enabled
• Business verification completed in Stripe

​

How It Works

1. Your organization connects an existing Stripe account to Fanfare
2. Fanfare creates charges on behalf of your connected account
3. Platform fees are automatically deducted from each transaction
4. Payouts go directly to your Stripe account’s bank account

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Consumer   │────▶│   Fanfare   │────▶│   Stripe    │
│  Payment    │     │   Platform  │     │   Connect   │
└─────────────┘     └─────────────┘     └─────────────┘
                           │                    │
                           │   Platform Fee     │
                           │◀──────────────────▶│
                           │                    │
                           │                    ▼
                           │            ┌─────────────┐
                           │            │    Your     │
                           └───────────▶│   Stripe    │
                                        │   Account   │
                                        └─────────────┘

​

Setup

​

Step 1: Navigate to Payment Settings

1. Go to Settings > Payments in the Fanfare admin
2. You’ll see the Stripe Connect card

​

Step 2: Connect Your Stripe Account

1. Click Connect with Stripe
2. You’ll be redirected to Stripe’s OAuth flow
3. Log in to your Stripe account (or create one)
4. Authorize Fanfare to access your account
5. You’ll be redirected back to Fanfare

​

Step 3: Verify Connection

• Your Stripe account ID
• Account display name
• Connection status (Active, Pending, or Error)
• Charges enabled status
• Payouts enabled status

​

Connection Status

​

Status Indicators

​

Charges Enabled

1. Log in to your Stripe dashboard
2. Complete any pending verification requirements
3. Fanfare will automatically update the status via webhooks

​

Payouts Enabled

1. Add a bank account in your Stripe dashboard
2. Complete identity verification if required
3. Status updates automatically via webhooks

​

Webhooks

​

Subscription Events

​

Payment Events

​

Connect Account Events

​

Webhook Security

// Webhook signature verification
const event = await stripe.webhooks.constructEventAsync(body, signature, webhookSecret);

​

Platform Fees

​

How Fees Work

• The fee percentage is set at the organization level
• Fees are automatically deducted from the transaction amount
• The remaining amount goes to your Stripe account

​

Viewing Your Fee Rate

1. Navigate to Settings > Payments
2. Your current platform fee rate is displayed
3. The effective rate may differ based on your subscription plan

​

Disconnecting

1. Go to Settings > Payments
2. Click Disconnect on the Stripe card
3. Confirm the disconnection

​

What Happens When You Disconnect

• No new charges can be processed through Fanfare
• Existing refunds can still be processed directly in Stripe
• Historical transaction data remains in Fanfare
• You can reconnect at any time with the same or different account

​

API Reference

​

Get Connection Status

GET /api/payment-providers/stripe/status

{
  "connected": true,
  "status": "ACTIVE",
  "accountId": "acct_1234567890",
  "displayName": "My Store",
  "chargesEnabled": true,
  "payoutsEnabled": true
}

​

Initiate Connection

GET /api/payment-providers/stripe/auth/url

{
  "url": "https://connect.stripe.com/oauth/authorize?..."
}

​

Disconnect Account

DELETE /api/payment-providers/stripe

{
  "success": true
}

​

Payment Flows

​

Auction Payments

1. Consumer receives winning notification with payment link
2. Consumer enters payment details
3. Charge is created on the connected Stripe account
4. Platform fee is deducted
5. Order is marked as paid

​

Queue/Draw Winner Payments

1. Winner receives checkout link
2. Payment is processed at checkout
3. Time limit enforced for checkout completion
4. Inventory released if payment not completed

​

Testing

​

Test Mode

1. Toggle to test mode in your Stripe dashboard
2. Connect using test mode OAuth
3. Use Stripe test cards for transactions

​

Test Card Numbers

​

Troubleshooting

​

Common Issues

• Log in to Stripe dashboard
• Complete pending verification steps
• Wait for Stripe to review (usually 1-2 business days)

• Ensure you’re logged into the correct Stripe account
• Check that browser cookies are enabled
• Try clearing cache and reconnecting

• Verify the webhook endpoint in Stripe dashboard
• Check webhook signing secret matches
• Review Stripe webhook logs for delivery failures

• Reconnect from Settings > Payments
• Contact Stripe support if issue persists

​

Checking Webhook Delivery

1. Go to Developers > Webhooks
2. Find the Fanfare endpoint
3. Check recent delivery attempts
4. Review any failed deliveries

​

Security

​

Data Handling

• Fanfare never stores full card numbers
• Payment details are handled entirely by Stripe
• Only tokenized references are stored

​

OAuth Security

• State parameter prevents CSRF attacks
• Tokens are exchanged server-side only
• Connected account IDs are validated

​

Webhook Verification

• All webhooks require valid signatures
• Timestamps are validated to prevent replay attacks
• Events are processed idempotently

​

Limitations

​

Related Resources

• Auction Payments
• Order Management
• Stripe Connect Documentation