// guide
Connecting Stripe
Payments and seller verification run on your own Stripe account. You are the Connect platform, your sellers are your connected accounts, and Stripe bills its fees to you directly. We never add to them.
Before you start
- A Stripe account with Connect set up. Stripe asks a few questions the first time you open Connect in its dashboard.
- One key per mode: a test key (
rk_test_) for your test marketplace, and a live key (rk_live_) for your live one. A test key is refused in live mode, and the other way round.
Make a restricted key
- In the Stripe dashboard, open Developers, then API keys, then Create restricted key.
- Name it MarketSDK, and set each permission in the table below. Leave every other permission at None.
- Create it, copy it, and paste it into the MarketSDK dashboard under stripe, in the matching mode.
| stripe section | permission | access | what we use it for |
|---|---|---|---|
| Core | Accounts | Write | Create sellers' connected accounts and read their status |
| Connect | Account Links | Write | Onboarding links for sellers |
| Connect | Transfers | Write | Release funds to a seller, and reverse them on a refund |
| Core | Payment Intents | Write | Buyer payments, and cancelling unpaid ones |
| Core | Charges and Refunds | Write | Refunds, full and partial |
| Checkout | Checkout Sessions | Write | Hosted checkout, and expiring unpaid sessions |
| Identity | Verification Sessions and Reports | Write | Seller identity verification |
| Core | Disputes | Read | Reading card disputes, to link them to orders |
| Webhook Endpoints | Webhook Endpoints | Write | Registering our endpoint on your account |
A full secret key (sk_) works too, but gives us more than we need. Prefer the restricted key.
What we check
- Before we store the key, we try each permission with a harmless request. The dashboard shows each one as granted or missing, and the key is refused until every one is granted.
- We check again every day, and after any Stripe call that is refused. If you edit or roll the key in Stripe, paste the new one; a failing key shows as invalid, and payments stop with
stripe_credential_invaliduntil you do. - The key is stored encrypted with AES-256-GCM, under a key only our servers hold. Nobody sees it again, in the dashboard or through the API; only its last four characters are shown.
- We register two webhook endpoints on your Stripe account, one for your account and one for your connected accounts, so we hear about payments, payouts, and card disputes. Removing the key removes them.
Replace or remove the key
Paste a new key over the old one at any time; it must belong to the same Stripe account. To remove the key, first turn off payments and seller verification for that mode.