Guides

Building Marketplace payment integration with Stripe Conn...

This guide provides a structured approach to implementing core marketplace functionality, focusing on payment handling, trust systems, and search matching. Key tools include Stripe Connect for payments, Algolia for search, and Clerk for authentication. Address common challenges like supply-demand balancing and role-based access control.

2-3 hours5 steps
1

Design core database schema

Create tables for users, listings, transactions, and reviews. Use PostgreSQL with foreign keys to enforce relationships. Include fields for user roles (buyer/seller), listing categories, and transaction statuses.

database/schema.sql
CREATE TABLE users (
  id UUID PRIMARY KEY,
  role VARCHAR(10) CHECK (role IN ('buyer', 'seller')),
  verified BOOLEAN DEFAULT FALSE
);

CREATE TABLE listings (
  id UUID PRIMARY KEY,
  seller_id UUID REFERENCES users(id),
  title VARCHAR(255),
  price DECIMAL(10,2),
  category VARCHAR(50)
);

⚠ Common Pitfalls

  • •Missing foreign key constraints leading to orphaned records
  • •Insufficient indexing on frequently queried columns
2

Implement Stripe Connect payment flow

Set up connected accounts for sellers using Stripe Connect. Configure platform fees and transfer splits. Use webhooks to update transaction statuses when payments are captured.

src/payments/stripe.js
const { Stripe } = require('stripe');
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

async function createTransfer({ amount, sellerAccountId }) {
  return await stripe.transfers.create({
    amount: Math.round(amount * 100),
    currency: 'usd',
    destination: sellerAccountId,
    transfer_group: 'order_123'
  });
}

⚠ Common Pitfalls

  • •Not handling webhook signatures leading to security vulnerabilities
  • •Incorrectly calculating platform fees during splits
3

Build trust system with reviews and verification

Implement a 5-star rating system with review text. Add verification steps for seller accounts using Clerk's email verification. Store review data in a separate table linked to transactions.

src/trust/reviews.js
async function createReview({ userId, listingId, rating, comment }) {
  if (!(await checkTransactionExists(userId, listingId))) {
    throw new Error('Cannot review un-purchased item');
  }
  return await db.query(`
    INSERT INTO reviews (user_id, listing_id, rating, comment)
    VALUES ($1, $2, $3, $4)
    RETURNING *`,
    [userId, listingId, rating, comment]
  );
}

⚠ Common Pitfalls

  • •Allowing anonymous reviews that damage platform credibility
  • •Not rate-limiting review submissions for spam prevention
4

Configure Algolia search with relevance scoring

Index listings in Algolia with attributes for title, category, and price range. Use custom ranking to prioritize verified sellers and recent listings. Implement faceted search for filtering.

src/search/algolia.js
const index = client.initIndex('listings');
await index.setSettings({
  attributesToIndex: ['title', 'category', 'price'],
  customRanking: ['desc(verified)', 'desc(created_at)'],
  searchableAttributes: ['title', 'description']
});

⚠ Common Pitfalls

  • •Overloading search indices with non-essential fields
  • •Not implementing query rate limiting for search endpoints
5

Implement role-based access control

Use Clerk's session management to enforce permissions. Restrict seller-only actions (listing creation, price changes) to users with 'seller' role. Validate permissions at both API and UI layers.

src/middleware/sellerMiddleware.js
function requireSellerRole(req, res, next) {
  const user = req.auth.user;
  if (user.role !== 'seller') {
    return res.status(403).json({ error: 'Seller access required' });
  }
  next();
}

⚠ Common Pitfalls

  • •Bypassing permission checks in client-side code
  • •Not auditing role assignment logic for security flaws

What you built

This implementation addresses core marketplace requirements while mitigating common pitfalls. Verify all payment flows with Stripe's test mode, stress-test search endpoints, and continuously monitor trust system metrics. Expand with AI features like recommendation engines or dynamic pricing as needed.