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.
Do both steps in your live Stripe account, not a Sandbox. Stripe's dashboard has an environment picker at the top of the page — if it shows a sandbox name, switch to your live account before continuing. Stripe lets you complete both pages inside a sandbox without any warning, but that has no effect on your live marketplace and seller onboarding keeps failing. (Using test-mode keys on purpose? Then complete them inside that same sandbox instead.)
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.
- The loss-liability item must end up with your marketplace (not Stripe) as the party responsible for losses. Prometora creates every seller account with your platform as the fees and loss collector, so Stripe requires these acknowledgements before it lets your keys create a single seller account.
- If skipped, onboarding fails with "Please review the responsibilities of collecting requirements for connected accounts." Stripe sometimes reports this same gap as account_create_activation_required / "Your account must be activated in order to create accounts" even when your account is fully activated and already taking payments - if you see that and your account is live, it is the Platform profile acknowledgements or the identity check below that is missing, not activation.
- Already done both pages and still blocked? Open Settings → Connect → Platform setup and check the Negative balance liability row. If it says "Stripe is responsible for losses", your original Connect setup chose the low-responsibility model and the Platform profile page may not offer the loss-liability acknowledgement. Ask Stripe support (chat from the Dashboard) to switch your platform profile to platform is liable for losses, then click Re-check in Prometora.
3. Verify your identity - the Connect "Go live" check:
- In Stripe open Connect, expand the Setup guide panel (bottom right) and look under Go live. Complete Verify your identity, then Confirm your integration choices (it unlocks once identity is verified).
- The account owner must do the identity step themselves, usually with a photo ID - a team member with Developer access cannot do it on their behalf. Stripe's own error for this state points at dashboard.stripe.com/account/onboarding.
- Until it is done the Platform profile page says "Onboarding incomplete" even with both acknowledgements ticked, and every seller Connect attempt fails with account_create_activation_required.
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
Pick your environment: your live account for live keys, or a Sandbox for test keys
Test keys belong on your Prometora sandbox, not on your real store. A seller who connects Stripe while test keys are in has to set up payouts again after you switch to live keys (Prometora removes the test connection for you).
In the current Stripe dashboard, test mode lives in Sandboxes - use the environment picker at the top of the page (older dashboards had a "Test mode" toggle in the top-right corner)
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.
Stripe tells Prometora when a seller finishes onboarding, disconnects, gets paid out, or is refunded, through one webhook destination on your Stripe account. Two events are required; three more add seller payout emails and refund tracking.
One-click setup (recommended)
Prometora uses the secret key you already saved to set the webhook up in your Stripe account for you. No copying URLs, events or signing secrets. Prometora only uses your key to run your marketplace's payments and this webhook, and you can roll the key in Stripe at any time and paste the new one into Prometora.
- Save your Stripe API keys (step 1 in Store Settings → Payments → Stripe Connect).
- In step 2, Webhook Endpoint, click Set up webhook for me.
- Prometora creates the webhook with the Connected accounts scope and all five events below, and saves its signing secret. The step turns green and shows Working.
The webhook step also checks your Stripe account every time you open the Payments tab and tells you what it finds:
| Status | What it means |
|---|---|
| Working | One webhook, the right scope and events, and the signing secret saved. Once a seller does something in Stripe, it also shows when the last event arrived. |
| Setup pending | There is no webhook in your Stripe account yet. Click Set up webhook for me. |
| Needs fixing | A webhook exists but something is wrong, and the step lists exactly what: set to “Your account” instead of “Connected accounts”, disabled by Stripe, a required event missing, more than one webhook pointing to Prometora, or a signing secret that doesn't match. Click Fix it for me. |
If something is off, the banner at the top of the Payments tab says so, and its link takes you straight to the webhook step, which lists what is wrong:
- Fix it for me creates a new, correct webhook and removes the old ones that point to Prometora. Other webhooks in your Stripe account are never touched, and it asks before replacing anything.
- Test and live mode each have their own webhooks. After switching from test to live keys, click the button once more for live. In a sandbox it works the same with your test keys.
- With a restricted key (
rk_...) that isn't allowed to manage webhooks, Prometora can't check or create it. Use the manual steps below, they take about 5 minutes.
Set it up by hand: video walkthrough
Prefer to do it yourself in the Stripe Dashboard, or using a restricted key? These are the manual steps.
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.
Step by step
The same steps, with a picture of each Stripe screen. Your store's Payments tab shows them too, with a copy button for the URL and every event name.
Open Stripe Webhooks
In your Stripe Dashboard go to Developers → Webhooks (Stripe opens its Workbench), then click “Add destination”. Do this in your live account, not a Sandbox.
Choose scope and events (Stripe screen “Select events”)
Under “Event destination scope” select Connected accounts, not “Your account”. Seller events are delivered to the Connected accounts scope.
Then under “Events” click the All events tab (not “Suggested”), search for each of these and tick it:
- account.updated
- account.application.deauthorized
- payout.paid
- payout.failed
- charge.refunded
Choose destination type (Stripe screen “Choose destination type”)
Select Webhook endpoint (not Amazon EventBridge or Azure Event Grid).
Configure destination (Stripe screen “Configure your destination”)
Only two fields need filling in: a Destination name (any name, e.g. “Prometora”) and the Endpoint URL:
https://www.prometora.com/api/stripe-connect/webhookLeave everything else as it is (Events from, Payload style, API version, Description).
Add destination
Click “Add destination” to save the webhook in Stripe.
Copy the signing secret
Stripe now shows the destination's page. Scroll to Destination details, find Signing secret at the bottom, click Reveal and copy the value starting with
whsec_.Paste it into Prometora
In Store Settings → Payments → Stripe Connect → Webhook Endpoint, paste the secret and save. The section shows Working and you are done.
Webhook events
| Event | Purpose |
|---|---|
| account.updated | Required. Marks the seller as verified when they finish onboarding, releases any sales held for them, grants the Stripe-verified badge and sends the welcome email |
| account.application.deauthorized | Required. Removes the seller's Stripe connection if they disconnect their account |
| payout.paid | Emails the seller when a payout lands in their bank |
| payout.failed | Emails the seller when a payout bounces |
| charge.refunded | Lets Prometora see refunds issued directly in the Stripe Dashboard (refunds from your Orders page are handled without it) |
Same steps in your dashboard
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
Which rate applies to a sale
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: by default Stripe's processing fee comes out of the seller's share, not your commission. You can choose to pay it yourself, see Card Fee below
Card Fee: Seller or You
Stripe charges a fee on every card payment. Under Commission & Fees in the Payment tab you choose who carries it. The choice applies to product orders, custom offers and bookings.
- The seller pays (the default). The card fee on the item price comes out of the seller's payout, on top of your commission. This is how marketplaces like Etsy and eBay work. If you also charge a buyer service fee, the card fee on that fee comes out of the fee, not out of the seller.
- You pay. Sellers receive the price minus your commission and nothing else. Stripe's fee comes out of what you keep. This suits a "sellers keep 95%" or "free to sell" promise, usually together with a buyer service fee that covers the cost.
The same $100.00 sale at 10% commission. Stripe's card fee is $3.20 (2.9% + $0.30) either way
One payment, one card fee
If you also charge a buyer service fee, the buyer still makes one payment and Stripe still charges one card fee, on the whole amount. With The seller pays, that one fee is split: the seller covers the part on their item price, and you cover the small part on your buyer fee. With You pay, all of it is yours.
$100.00 item + $6.00 buyer fee, with "The seller pays"
The fixed $0.30 is charged once per payment and stays in the seller's part
Check your margin before you switch
Buyer Service Fee
The commission above is paid by the seller. You can also charge the buyer a fee on top of the item price, the way Vinted does with its buyer protection fee. Use it to split your take between both sides (for example 5% from the seller and 5% from the buyer), or to make selling free and earn from buyers only. Turn it on under Commission & Fees in the Payment tab.
- Percent of the item price, calculated on the items after any coupon and before shipping.
- Fixed amount per checkout (optional), added once per order, however many items or sellers are in it.
- Fee name, shown to buyers, for example "Service fee" or "Buyer protection". Leave it empty to use "Service fee" in your store's language.
- Explanation shown to buyers (optional, up to 200 characters): one line behind the (i) next to the fee on the listing page and in the cart, saying what the fee pays for. Leave it empty for the default text in your store's language.
Buyers see the fee before they pay. The listing page shows a small breakdown above the Buy now button: the item price, the fee with its (i), the shipping cost when your store prices shipping up front (flat rate or a per-listing price, "Free" above your free-shipping threshold, nothing for live carrier rates), and the total. Each line appears only when it applies, so a store without a buyer fee or without shipping looks as before. The fee is also its own line in the cart and on a custom offer in chat, and a separate line on the Stripe checkout page, the order confirmation email and the buyer's order page.
$100.00 item, 5% seller commission, buyer fee of 5% + $1.00
The seller receives the same $91.80 with or without the buyer fee ($100.00 minus $5.00 commission minus $3.20 card fee)
How the buyer fee is handled
- Sellers never see the fee. Their payout, their sale email and their sales page are based on the item price only.
- Who pays the card fee on the item price follows the Card Fee setting. The card fee on the buyer fee itself always comes out of the fee.
- Your Prometora transaction fee is calculated on the item price only, not on the buyer fee or on shipping.
- A refund returns the fee with the order. A partial refund returns it in the same proportion.
- It follows the listing type. Types that are bought (Buy now, cart, purchase requests and custom offers) are charged. Types that are booked through a calendar are not, and neither is a custom offer for such a listing.
- On a marketplace with both kinds, the setting lists which listing types are charged. On a marketplace where every listing type is booked, the setting is not available yet.
- While it is on, "Show fee breakdown at checkout" is not used, so buyers see one fee line.
Card surcharges and what you call the fee
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
If You Hold Seller Payouts
Some settings keep a seller's share in your Stripe balance for a while before it is transferred to the seller: shipping (held until the seller marks the order shipped), buyer confirmation (held until the buyer confirms delivery or the release period ends), booking payout after the session, and sellers who sell before finishing their Stripe onboarding (their earnings are parked until they connect). When the hold ends, the transfer to the seller is made from your balance.
Your automatic payout schedule does not know about these holds. A daily or weekly payout can move the held money to your bank before the release is due, and the transfer to the seller then fails for lack of balance. Prometora retries it every day and it goes through once your available balance covers it again. Until then your Orders tab shows the order as Payout failed, retrying, and the Payment tab in your store settings shows your current schedule, your balance and a warning.
The simplest fix is a payout delay of 7 days or more under Settings → Payouts in your Stripe Dashboard. Payouts stay automatic, your commission still reaches your bank a little later, and each sale's money stays in the balance long enough for the usual holds.
Manual payouts also work, and they are the better choice when you hold money for long periods, for example sellers who sell before finishing their Stripe onboarding. They move the responsibility to you: Stripe's Pay out button offers your whole available balance, including the money held for sellers, so leave at least the amount the Payment tab shows as Held for sellers right now in the balance each time you pay yourself out.
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