Docs

Payments & Stripe

Complete guide to setting up Stripe Connect for multi-vendor payments with automatic commission splitting.

Quick answer

Set up Stripe Connect so buyers can pay and sellers get paid. Three things: connect your Stripe account, set your commission rate, and configure the webhook so seller verification updates automatically. The webhook is the one step founders forget. Without it, deferred payouts do not process.

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

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:

Buyer
Pays full price
→
Stripe
Processes payment
→
Split
Your commission
→
Vendor
Receives payout

Detailed Payment Flow

  1. Buyer checks out: Customer enters payment details on your marketplace checkout page
  2. Payment captured: Stripe securely processes the payment and holds the funds
  3. Commission calculated: Your platform fee is automatically calculated based on your settings
  4. Funds split: Stripe splits the payment - your commission goes to your account, the rest to the vendor
  5. Vendor payout: Vendor receives their portion according to the payout schedule
  6. 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:

Buyer pays $100
Full price, single charge at checkout
You · 10%
Vendor · 90%
$10
$90
$10 → You
Your platform commission, paid out to your bank account
$90 → Vendor
The vendor's earnings, paid out on their Stripe schedule

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.

Sale completes
Buyer is charged, vendor not yet verified
↓
Earnings held
Tracked as the vendor's pending balance
↓
Auto-released
Paid out as soon as onboarding finishes
How deferred onboarding & held earnings work

Prerequisites

Before setting up payments, you'll need:

1

A Stripe Account

Create a free account at stripe.com if you don't have one

2

Business Information

Legal business name, address, tax ID (EIN in US), and bank account details

3

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

  1. Go to Store Settings → Payments in your Prometora dashboard
  2. Click the "Connect with Stripe" button
  3. You'll be redirected to Stripe to authorize the connection
  4. Log in to your Stripe account (or create one)
  5. Review and accept the Stripe Connect terms
  6. You'll be redirected back to Prometora with your account connected
Connect with Stripe

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

Public

Used in frontend code (browser). Safe to expose publicly.

pk_test_51AcYn...xxxxxx
  • • Starts with pk_test_ (test) or pk_live_ (production)
  • • Used to create payment tokens in the browser
  • • Cannot access sensitive data or make charges directly

Secret Key

Private

Used in backend/server code only. Never expose publicly!

sk_test_51AcYn...xxxxxx
  • • Starts with sk_test_ (test) or sk_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:

ModeKey PrefixPurposeReal Money?
Test Modepk_test_ / sk_test_Development & testingNo - simulated only
Live Modepk_live_ / sk_live_Production - real customersYes - 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:

1

Log in to your Stripe Dashboard

2

Pick your environment: your live account for live keys, or a Sandbox for test keys

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)

3

Click Developers in the left sidebar

4

Click API keys in the submenu

5

Copy your Publishable key and Secret key

Click "Reveal test/live key" to see the secret key

Stripe Dashboard
Test mode
Publishable key
pk_test_51Abc...xxxxx
Secret key
sk_test_51Abc...••••••
Click to reveal

Adding Keys to Prometora

  1. Go to Store Settings → Payments in your Prometora dashboard
  2. Find the Stripe API Keys section
  3. Paste your Publishable Key in the first field
  4. Paste your Secret Key in the second field
  5. 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.

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.

Video Walkthrough

Video: Set up the Stripe Connect webhookSee all video guides

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.

  1. 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.

  2. 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

  3. Choose destination type (Stripe screen “Choose destination type”)

    Select Webhook endpoint (not Amazon EventBridge or Azure Event Grid).

  4. 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/webhook

    Leave everything else as it is (Events from, Payload style, API version, Description).

  5. Add destination

    Click “Add destination” to save the webhook in Stripe.

  6. 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_.

  7. Paste it into Prometora

    In Store Settings → Payments → Stripe Connect → Webhook Endpoint, paste the secret and save. The section shows Configured and you are done.

Webhook events

EventPurpose
account.updatedRequired. 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.deauthorizedRequired. Removes the seller's Stripe connection if they disconnect their account
payout.paidEmails the seller when a payout lands in their bank
payout.failedEmails the seller when a payout bounces
charge.refundedLets Prometora see refunds issued directly in the Stripe Dashboard (refunds from your Orders page are handled without it)

Same steps in your dashboard

Store Settings → Payments → Stripe Connect → Webhook Endpoint shows these steps with copy buttons for the URL and each event name, and turns green once the signing secret is saved.

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?

For a complete guide on commission rates and fee structures, see our Revenue & Fees documentation. You can also use the Revenue Calculator to project your marketplace earnings.
%

Example: 15% commission

Which rate applies to a sale

This is the store-wide default. When more than one rate could apply, the most specific one wins: a rate set on an individual seller under Managed Sellers, then the seller's subscription plan rate, then the listing type rate, then this default. Per-type rates let you charge, say, 6% on tack and 12% on riding lessons in the same store.

Commission Rate Guidelines

RateBest ForExamples
5-10%High-volume, low-margin goodsElectronics, commodities
10-15%Standard product marketplacesHandmade goods, vintage items
15-20%Service marketplacesFreelance, consulting
20-30%Premium/value-added servicesShort-term rentals, luxury goods

Commission Calculation Example

Sale Price
$100.00
Your Commission (15%)
$15.00
Stripe Fees (~2.9% + $0.30)
-$3.20
Vendor Receives
$81.80

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:

1

Click "Become a Seller"

Vendor visits your marketplace's seller signup page

2

Create Prometora Account

Sign up with email or social login

3

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)
4

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:

Credit Cards
Visa, MC, Amex
🍎
Apple Pay
iOS & Safari
🔵
Google Pay
Android & Chrome
Bank Transfers
ACH, SEPA

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:

RegionPayout SpeedNotes
United States2 business daysStandard for established accounts
Europe (SEPA)3-5 business daysVaries by country
UK2-3 business daysFaster Payments supported
New Accounts7-14 daysInitial 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 TypeFee (US)Example ($100 sale)
Credit/Debit Cards2.9% + $0.30$3.20
International Cards+1.5%$4.70 total
ACH Bank Transfer0.8% (max $5)$0.80
Connect Fee+0.25% + $0.25/payoutPer active vendor

Who Pays Stripe Fees?

Stripe processing fees (2.9% + $0.30) are deducted from the seller's portion along with your platform commission. This is the industry-standard model used by marketplaces like Etsy and eBay — sellers absorb all transaction-related 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

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:

  1. Stripe notifies you of the dispute
  2. The disputed amount is held pending resolution
  3. You have 7-21 days to submit evidence
  4. The bank makes a final decision

Dispute fee: $15 per dispute (refunded if you win)

Marketplace operator responsibilities

On Prometora marketplaces, sellers do not have their own Stripe-side dashboard. That means you, the marketplace owner, defend disputes and bear the financial liability if a seller cannot cover a chargeback. This is the standard model for white-labeled Stripe Connect marketplaces - but it is a real risk you take on. See What This Setup Means for Your Risk Exposure for the full breakdown and how to manage it.

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

Success:4242 4242 4242 4242
Decline:4000 0000 0000 0002
Requires Auth:4000 0025 0000 3155

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! Not on a plan yet? Compare Prometora pricing to find the right tier for your marketplace.
ModerationHow Sellers Connect Stripe
Payments & Stripe | Prometora Docs