Payments & Stripe
Complete guide to setting up Stripe Connect for multi-vendor payments with automatic commission splitting.
Quick answer
What is Stripe Connect?
Stripe Connect is Stripe's solution for marketplace payments — see our Stripe for marketplaces guide for a deeper look at how it compares to regular Stripe. 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
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
Where the Money Goes
Here is a concrete example. A buyer pays $100 for a vendor's listing on a marketplace with a 10% platform fee. The split happens automatically inside Stripe:
Stripe processing fees (~2.9% + 30¢) are deducted separately by Stripe. Change your rate anytime under Settings → Payments.
What If the Vendor Hasn't Finished Onboarding?
Vendors can list and sell before they finish Stripe verification. When that happens, their share is held safely and released automatically the moment they complete onboarding - no manual transfer needed.
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
⚠️ Required: complete your Connect platform setup (one-time)
Before any seller can be onboarded, your own Stripe account needs two one-time steps. Until both are done, seller onboarding fails - the seller sees a generic "Failed to connect Stripe account" message, while your server logs (or the request's Network response) show the specific Stripe reason below.
1. Platform setup - get approved to create connected accounts:
- Open dashboard.stripe.com/settings/connect/platform-setup (Settings → Connect → Platform setup) and complete it.
- Stripe emails you "…is approved to create live accounts and charges" once this clears.
- If skipped, onboarding fails with non_connect_platform_accounts_v2_access_blocked / "Only Stripe Connect platforms can work with other accounts."
2. Platform profile - acknowledge your platform responsibilities:
- Open dashboard.stripe.com/settings/connect/platform-profile (Settings → Connect → Platform profile) and click Acknowledge on each item - the refunds & chargebacks (loss) liability and collecting requirements for connected accounts.
- If skipped, onboarding fails with "Please review the responsibilities of collecting requirements for connected accounts."
Also finish any "Onboarding incomplete → View onboarding" step shown on those pages. It's a one-time setup per Stripe account.
Not sure if you're done? Once your Connect keys are saved in Store Settings → Payments, Prometora checks this for you and shows a green “Your sellers can connect” confirmation when it's complete - or a banner with the exact fix link if a step is still missing. You can re-run it anytime with the Check that sellers can connect button there.
What you'll see on the Payments tab
Your sellers can connect
Your Stripe Connect platform setup is complete.
Checked just now · Re-check
Your sellers can't connect yet
A one-time setup step is still missing.
Open Stripe to fix this
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
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
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
Webhooks for Stripe Connect
Using basic Stripe instead? If you're running a single-vendor store without seller payouts, you can skip this section. Webhooks are only required for Stripe Connect marketplaces.
To track when sellers complete their Stripe onboarding, you need to configure a webhook with two events. This allows Prometora to automatically update seller verification status.
Video Walkthrough
Sandbox vs. Production
This video is recorded in Stripe's Sandbox (test mode) for demonstration. When setting up your live marketplace, follow the exact same steps in your Live/Production Stripe dashboard, then paste the live signing secret into Prometora. The secret must match the mode of your Stripe keys — test secret with test keys, live secret with live keys.
API version
Any version works — just pick the latest (or keep your account's default). Prometora only reads fields that have been stable across every Stripe API version.
Required Webhook Events
| Event | Purpose |
|---|---|
| account.updated | Updates seller verification status when they complete Stripe onboarding |
| account.application.deauthorized | Removes seller's Stripe connection if they disconnect their account |
Where to Set Up Webhooks
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:
Want to learn more about making money?
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
An embedded Stripe form opens right inside your marketplace — no redirect to a Stripe-branded page. Prometora prefills their name, country, website, and business category, so it only takes a few minutes.
- • Personal details (name, DOB, address, phone where required)
- • Identity verification (SSN or ID upload, if Stripe asks)
- • Bank account for payouts
- • Tax details where required (e.g. W-9 in the US)
Payouts Unlocked
Once verified, the vendor receives payouts — and any earnings they accrued before verifying pay out automatically. With deferred onboarding, vendors can list and sell first; verifying is only needed to get paid.
Supported Payment Methods
Stripe automatically enables the best payment methods for your customers based on their location:
Local Payment Methods
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?
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
- Who funds the refund: This is handled automatically. If the seller was already paid for the sale, their share is pulled back from their account as part of the refund; your commission on that sale is returned too. If the seller hadn't been paid yet (for example a shipping order not yet shipped), the funds simply never leave your balance. Either way, the buyer gets the full refund and the seller does not keep earnings from a refunded sale.
- Refund timing: 5-10 business days to appear on customer's statement
Important: Refund Fees
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)
Marketplace operator responsibilities
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-K generation for US vendors, issued by Stripe per current IRS thresholds. Taxes & 1099s
Troubleshooting
"Account not fully onboarded"
The vendor hasn't completed all Stripe verification steps. They should check their email for Stripe's requests and finish any outstanding items from the Financesection of their seller dashboard (account management is mounted inline there).
"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