Payments

​

Payment Architecture

​

Two-Sided Marketplace

• Organizations: Pay for bounties using Stripe Checkout
• Contributors: Receive payouts via Stripe Connect accounts
• Platform: Facilitates secure escrow and transfers

​

Payment Flow Overview

​

Platform Fees

​

Funding Bounties

​

Creating Checkout Session

const bounty = await trpc.bounties.createBounty.mutate({
  title: "Implement feature X",
  amount: "500.00",
  currency: "USD",
  payLater: false // Fund now via checkout
});

// Returns:
// - bounty: Created bounty record
// - checkoutUrl: Stripe Checkout URL
// - fees: Platform fees amount
// - totalWithFees: Total charge amount

​

Stripe Customer Creation

• Created on first bounty funding
• Customer ID stored in organization record
• Reused for all future bounties
• Verified and recreated if missing from Stripe

​

Payment Confirmation

1. User completes Stripe Checkout
2. Stripe sends checkout.session.completed webhook
3. Platform captures payment and updates bounty
4. Bounty status changes from draft to open
5. Payment status changes from pending to held

​

Stripe Connect Integration

​

Connect Account Setup

​

Initiating Onboarding

const link = await trpc.connect.createConnectAccountLink.mutate();

// Redirects user to Stripe onboarding
// Returns URL for Express Dashboard onboarding flow
window.location.href = link.data.url;

​

Account Status

const status = await trpc.connect.getConnectStatus.query();

// Returns:
// - hasConnectAccount: Account exists
// - onboardingComplete: Identity verified
// - cardPaymentsActive: Can receive card payments
// - transfersActive: Can receive transfers
// - accountDetails: Detailed requirements and capabilities

​

Account Requirements

• Currently Due: Must be provided to receive payouts
• Eventually Due: Will be required in the future
• Past Due: Overdue requirements blocking payouts

​

Express Dashboard

• Banking information
• Payout schedule
• Tax information
• Identity verification
• Transaction history

const dashboard = await trpc.connect.getConnectDashboardLink.mutate();

// Returns:
// - url: Dashboard or onboarding link
// - isOnboarding: true if onboarding incomplete

​

Receiving Payouts

​

Payout Creation

1. Platform creates transfer to Connect account
2. Payout record created with pending status
3. Stripe processes transfer
4. Payout status updates to processing then completed
5. Funds appear in Connect account balance
6. Stripe handles bank deposit based on payout schedule

​

Payout Statuses

• pending: Transfer initiated, awaiting processing
• processing: Stripe processing the transfer
• completed: Successfully transferred to Connect account
• failed: Transfer failed (retried automatically)

​

Viewing Payout History

const history = await trpc.connect.getPayoutHistory.query({
  page: 1,
  limit: 20
});

// Returns paginated list of payouts:
// - Payout amount
// - Status
// - Associated bounty
// - Stripe transfer ID
// - Timestamps

​

Account Balance

const balance = await trpc.connect.getAccountBalance.query();

// Returns:
// - available: Funds ready for payout
// - pending: Funds being processed
// - total: Combined available + pending

​

Transaction Records

​

Transaction Types

• payment_intent: Initial bounty funding
• transfer: Payout to contributor
• refund: Cancelled bounty refund
• payout: External bank payout

​

Transaction Details

• Bounty ID
• Transaction type
• Amount
• Stripe ID for verification
• Timestamp

​

Activity Tracking

const activity = await trpc.connect.getActivity.query({
  page: 1,
  limit: 20
});

// Returns combined activity:
// - Payouts received (as contributor)
// - Bounties created (as organization)
// - Associated bounty details
// - Status and amounts

​

Refunds

1. Cancellation request approved
2. Payment intent cancelled in Stripe
3. Refund created for original amount
4. Funds returned to organization’s payment method
5. Transaction recorded with type refund

​

Security Features

​

Payment Locks

• Idempotent payment processing
• Operation tracking prevents double-charging
• Redis-based distributed locking
• Automatic lock expiration

​

Circuit Breaker

• Monitors Stripe API health
• Automatically opens circuit on repeated failures
• Prevents cascade failures
• Auto-recovery when Stripe is healthy

​

Webhook Verification

• Signature validation
• Event deduplication
• Secure endpoint authentication
• Automatic retry on failure

​

Common Issues

​

Best Practices

​

Payment Support

1. Check Stripe Express Dashboard for detailed error messages
2. Review platform activity logs
3. Contact support with transaction/payout ID
4. For Stripe account issues, contact Stripe support directly