Payments & Stripe
Complete guide to setting up Stripe Connect for multi-vendor payments with automatic commission splitting.
What is Stripe Connect?
Stripe Connect is Stripe's solution for marketplace payments. It allows you to:
- Accept payments from buyers on behalf of your vendors
- Automatically split payments between you and vendors
- Handle vendor payouts without manual transfers
- Comply with payment regulations in 40+ countries
- Manage tax reporting and 1099s (in the US)
Why Prometora Uses Stripe Connect
Stripe Connect is the industry standard for marketplace payments, used by Lyft, Shopify, Instacart, and thousands of marketplaces. It handles the complex compliance and money movement so you can focus on building your marketplace.
How Payments Work
Here's the complete flow when a buyer makes a purchase on your marketplace:
Detailed Payment Flow
- Buyer checks out: Customer enters payment details on your marketplace checkout page
- Payment captured: Stripe securely processes the payment and holds the funds
- Commission calculated: Your platform fee is automatically calculated based on your settings
- Funds split: Stripe splits the payment - your commission goes to your account, the rest to the vendor
- Vendor payout: Vendor receives their portion according to the payout schedule
- Your payout: Your commission is transferred to your bank account
Prerequisites
Before setting up payments, you'll need:
A Stripe Account
Create a free account at stripe.com if you don't have one
Business Information
Legal business name, address, tax ID (EIN in US), and bank account details
Identity Verification
Stripe may require ID verification for the account owner (government ID, SSN in US)
Setting Up Stripe Connect
Step 1: Connect Your Stripe Account
- Go to Store Settings → Payments in your Prometora dashboard
- Click the "Connect with Stripe" button
- You'll be redirected to Stripe to authorize the connection
- Log in to your Stripe account (or create one)
- Review and accept the Stripe Connect terms
- You'll be redirected back to Prometora with your account connected
Click this button in Store Settings → Payments
Stripe API Keys
API keys are credentials that allow Prometora to communicate securely with your Stripe account. You'll need to add these keys in Store Settings → Payments.
Types of API Keys
Stripe provides two types of keys, each with a specific purpose:
Publishable Key
PublicUsed in frontend code (browser). Safe to expose publicly.
- • Starts with
pk_test_(test) orpk_live_(production) - • Used to create payment tokens in the browser
- • Cannot access sensitive data or make charges directly
Secret Key
PrivateUsed in backend/server code only. Never expose publicly!
- • Starts with
sk_test_(test) orsk_live_(production) - • Full access to your Stripe account
- • Can create charges, refunds, access customer data
Security Warning
Never share your Secret Key publicly - not in client-side code, GitHub repositories, screenshots, or support tickets. If your Secret Key is compromised, roll it immediately in the Stripe Dashboard.
Test Mode vs Live Mode
Stripe provides two separate environments, each with its own set of API keys:
| Mode | Key Prefix | Purpose | Real Money? |
|---|---|---|---|
| Test Mode | pk_test_ / sk_test_ | Development & testing | No - simulated only |
| Live Mode | pk_live_ / sk_live_ | Production - real customers | Yes - real charges |
💡 Recommendation
Always start with Test Mode keys while building and testing your marketplace. Only switch to Live Mode when you're ready to accept real payments from customers.
How to Get Your API Keys
Follow these steps to find your API keys in the Stripe Dashboard:
Log in to your Stripe Dashboard
Toggle "Test mode" or "Live mode" in the top-right corner
The toggle shows which environment you're viewing
Click Developers in the left sidebar
Click API keys in the submenu
Copy your Publishable key and Secret key
Click "Reveal test/live key" to see the secret key
Adding Keys to Prometora
- Go to Store Settings → Payments in your Prometora dashboard
- Find the Stripe API Keys section
- Paste your Publishable Key in the first field
- Paste your Secret Key in the second field
- Click Save to store your keys securely
Your Keys Are Secure
Prometora encrypts your API keys before storing them. They are never exposed in logs, client-side code, or API responses.
Setting Up Webhooks
Webhooks allow Stripe to notify Prometora about events in real-time, such as successful payments, refunds, or disputes. This ensures your marketplace stays in sync with Stripe.
What Are Webhooks?
Webhooks are HTTP callbacks that Stripe sends to your marketplace when something happens:
Why Webhooks Matter
Payment Confirmation
Get notified instantly when a payment succeeds or fails, so orders can be processed immediately.
Refund Updates
Automatically update order status when refunds are processed.
Dispute Alerts
Get notified immediately when a customer disputes a charge.
Vendor Status
Know when vendors complete or fail their Stripe onboarding.
How to Create a Webhook
Follow these steps to set up a webhook in your Stripe Dashboard:
Click "Add endpoint" (or "Add destination")
Enter your Prometora webhook URL (found in Store Settings → Payments):
Select the events to listen to (see recommended events below)
Click "Add endpoint" to create the webhook
Copy the Signing secret (starts with whsec_) and add it to Prometora
Recommended Webhook Events
Select these events when creating your webhook endpoint:
| Event | Triggered When |
|---|---|
| checkout.session.completed | Customer completes checkout |
| payment_intent.succeeded | Payment is successfully captured |
| payment_intent.payment_failed | Payment attempt fails |
| charge.refunded | A refund is processed |
| charge.dispute.created | Customer disputes a charge |
| account.updated | Vendor's Stripe account status changes |
| account.application.deauthorized | Vendor disconnects from your platform |
| payout.paid | Payout successfully sent to bank |
| payout.failed | Payout fails |
Webhook Signing Secret
The signing secret (whsec_...) is used to verify that webhook requests actually come from Stripe and haven't been tampered with.
Finding Your Signing Secret
- 1. Go to Stripe Dashboard → Developers → Webhooks
- 2. Click on your webhook endpoint
- 3. Under "Signing secret", click "Reveal"
- 4. Copy the secret (starts with
whsec_) - 5. Paste it in Prometora → Store Settings → Payments → Webhook Signing Secret
Important: Test vs Live Webhooks
You need separate webhooks for Test mode and Live mode. Each has its own signing secret. Make sure you're using the correct secret for your environment.
Testing Webhooks
You can test webhooks directly from the Stripe Dashboard:
- Go to your webhook endpoint in the Stripe Dashboard
- Click "Send test webhook"
- Select an event type (e.g.,
payment_intent.succeeded) - Click "Send test webhook"
- Check the response - a 200 OK means success
Local Development with Stripe CLI
For local development, use the Stripe CLI to forward webhooks to your local machine:
Webhook Troubleshooting
"Signature verification failed"
- • Make sure you're using the correct signing secret for your environment
- • Check that you copied the entire secret (starts with
whsec_) - • Verify you're using test secret for test mode, live secret for live mode
"Endpoint not responding" or 404 errors
- • Verify your webhook URL is correct and publicly accessible
- • Check your marketplace is deployed and running
- • Ensure there's no firewall blocking Stripe's IP addresses
"Timed out" errors
- • Webhooks must respond within 30 seconds
- • Check for slow database queries or API calls
- • Consider processing webhooks asynchronously
Step 2: Complete Stripe Onboarding
After connecting, Stripe may require additional information to fully activate your account:
Business Details
- • Legal business name and DBA (if applicable)
- • Business address
- • Business type (sole proprietor, LLC, corporation, etc.)
- • Industry/MCC code
Bank Account
- • Bank account number
- • Routing number (US) or equivalent
- • Account holder name
Identity Verification
- • Account representative's name and DOB
- • Last 4 digits of SSN (US) or full ID
- • May require document upload (ID, utility bill)
Step 3: Configure Commission Rate
Set the percentage you take from each sale. This is your marketplace's revenue:
Example: 15% commission
Commission Rate Guidelines
| Rate | Best For | Examples |
|---|---|---|
| 5-10% | High-volume, low-margin goods | Electronics, commodities |
| 10-15% | Standard product marketplaces | Handmade goods, vintage items |
| 15-20% | Service marketplaces | Freelance, consulting |
| 20-30% | Premium/value-added services | Short-term rentals, luxury goods |
Commission Calculation Example
Note: Stripe fees are typically paid by the vendor, but this is configurable
Vendor Payment Onboarding
When vendors sign up on your marketplace, they complete Stripe's onboarding flow:
Click "Become a Seller"
Vendor visits your marketplace's seller signup page
Create Prometora Account
Sign up with email or social login
Complete Stripe Onboarding
Redirected to Stripe to verify identity and connect bank account. This typically takes 5-10 minutes.
- • Personal information (name, DOB, address)
- • Identity verification (SSN or ID upload)
- • Bank account for payouts
- • Tax information (W-9 in US)
Ready to Sell
Once verified, vendor can create listings and receive payments
Supported Payment Methods
Stripe automatically enables the best payment methods for your customers based on their location:
Local Payment Methods
Stripe automatically offers local payment methods like iDEAL (Netherlands), Bancontact (Belgium), Przelewy24 (Poland), and more based on buyer location.
Payouts
Vendor Payouts
Vendors receive automatic payouts to their connected bank account:
| Region | Payout Speed | Notes |
|---|---|---|
| United States | 2 business days | Standard for established accounts |
| Europe (SEPA) | 3-5 business days | Varies by country |
| UK | 2-3 business days | Faster Payments supported |
| New Accounts | 7-14 days | Initial verification period |
Your Commission Payouts
Your platform commission follows the same payout schedule as your Stripe account settings. You can configure this in your Stripe Dashboard:
- Daily: Receive payouts every business day
- Weekly: Receive one payout per week
- Monthly: Receive one payout per month
- Manual: Request payouts manually when needed
Stripe Fees
Stripe charges processing fees for each transaction. These are separate from your marketplace commission:
| Payment Type | Fee (US) | Example ($100 sale) |
|---|---|---|
| Credit/Debit Cards | 2.9% + $0.30 | $3.20 |
| International Cards | +1.5% | $4.70 total |
| ACH Bank Transfer | 0.8% (max $5) | $0.80 |
| Connect Fee | +0.25% + $0.25/payout | Per active vendor |
Who Pays Stripe Fees?
By default, Stripe fees are deducted from the vendor's portion. This is the most common setup for marketplaces. You can also choose to absorb these fees yourself by adjusting the payment split.
Refunds & Disputes
Processing Refunds
Refunds can be initiated from the Prometora dashboard or Stripe Dashboard:
- Full refunds: Return the entire payment amount
- Partial refunds: Return a portion of the payment
- Refund timing: 5-10 business days to appear on customer's statement
Important: Refund Fees
When you issue a refund, Stripe does not return the original processing fees. For a $100 sale with $3.20 in fees, if you refund the full amount, you lose the $3.20 fee.
Handling Disputes (Chargebacks)
If a customer disputes a charge with their bank:
- Stripe notifies you of the dispute
- The disputed amount is held pending resolution
- You have 7-21 days to submit evidence
- The bank makes a final decision
Dispute fee: $15 per dispute (refunded if you win)
Security & Compliance
PCI Compliance
Stripe is PCI Level 1 certified. Card data never touches your servers.
Fraud Prevention
Stripe Radar uses ML to block fraudulent payments automatically.
3D Secure
Additional authentication for high-risk transactions (SCA compliant in EU).
Tax Reporting
Automatic 1099 generation for US vendors earning over $600.
Troubleshooting
"Account not fully onboarded"
The vendor hasn't completed all Stripe verification steps. They should check their email for Stripe's requests or visit their Stripe Express dashboard.
"Payouts paused"
Stripe may pause payouts if there are verification issues or suspicious activity. Check the Stripe Dashboard for specific requirements.
"Payment failed"
Common causes: insufficient funds, expired card, bank decline, or fraud prevention. The customer should try a different payment method.
Testing Payments
Before going live, test your payment flow using Stripe's test mode:
Test Card Numbers
Use any future expiry date and any 3-digit CVC
Ready to Go Live?
Once you've tested everything, make sure your Stripe account is in live mode and all vendors have completed their onboarding. Then you're ready to accept real payments!