Connect Stripe

Give Supaffi a restricted Stripe key so it can follow sales, refunds and disputes.

Supaffi follows sales, renewals, refunds and disputes through Stripe. It needs a key that can read your payments, and a webhook so Stripe tells it when something happens. Each product has its own key and webhook.

Create a restricted key

Use a restricted key: it reads your payments and can create one webhook, nothing else. Supaffi builds the key form for you.

Open the Stripe account you sell with
The button in the next step opens Stripe on whichever account is open in your browser. Switch to the right one first.
Press Create the key in Stripe
It is on the Stripe key step of setup, Let Supaffi read your Stripe payments. Stripe opens its restricted key form, named Supaffi: <product>, with the permissions already ticked.
Check the permissions
Compare the form with the table below and set any row that is not ticked. Then create the key in Stripe and copy it. It starts with rk_live_.
Paste it into Supaffi
Paste the key into Paste the key here and press Continue. Supaffi checks it and creates the webhook. The step turns green with Supaffi can read your Stripe payments.

A full secret key (sk_live_) also works, but it can do anything on your account. Settings then shows This is a full account key. A restricted key is safer. with a link to create one.

If the key is refused

Message	What to do
That is not a Stripe secret or restricted key	Paste a key starting with `rk_` or `sk_`, not a publishable key.
The key is missing a permission. Create it from the button above.	Create a new key from the button and check every row in the table below.
That key cannot create webhooks. Create it from the button above, with every row ticked.	Set Webhook Endpoints to Write on a new key.
Stripe says this key is not valid	The key was mistyped, revoked or rolled. Create a new one.
Could not reach Stripe	Try again in a moment.

Permissions

The key needs these rows on Stripe's form, with the access shown.

Stripe row	Access	Why Supaffi needs it
Charges	Read	Checks whether a sale was refunded before its commission was recorded.
Checkout Sessions	Read	Reads the tax on a one-time sale.
Customers	Read	Matches a sale to its customer and checks whether that customer is excluded.
Disputes	Read	Holds a commission while its sale is disputed.
Invoices	Read	Reads what an invoice charged and whether it is excluded, and finds the payment behind a refund.
Payment Intents	Read	Reads the payment a commission is owed on.
Payment Methods	Read	Spots an affiliate buying through their own link.
Subscriptions	Read	Reads the products a referred subscription bills and whether it is excluded.
Webhook Endpoints	Write	Creates the endpoint that tells Supaffi about sales.

The webhook endpoint

A webhook is how Stripe tells Supaffi about a sale, a renewal, a refund or a dispute, the moment it happens. You do not create it. When you save the key, Supaffi adds an endpoint to your Stripe account:

Field	Value
URL	`https://<subdomain>/api/webhooks/stripe`
Description	`Supaffi: <product>`

It listens to these events:

Webhook events

checkout.session.completed
checkout.session.async_payment_succeeded
invoice.paid
charge.refunded
charge.dispute.created
charge.dispute.closed
customer.subscription.deleted

Supaffi keeps the endpoint's signing secret and checks it on every event. When Supaffi starts, and when you replace the key or secret, it adds any event missing from the list to an existing endpoint. An endpoint set to receive all events is left as it is.

Check the connection

Open Settings, then Connections. Under Stripe you see the key type (Restricted key or Full account key) and two rows.

supaffi.yourserver.com/dashboard

Connections

StripeRestricted key

Connected to Stripe

Receiving events from Stripe

Both rows green: the key works and Stripe is sending events.

Row	States
Key	No Stripe key yet, Connected to Stripe or Stripe rejected the key
Webhook	No webhook yet, Waiting for the first event from Stripe or Receiving events from Stripe

Waiting for the first event from Stripe is normal until your first payment after connecting.

Replace a key or signing secret

Each row in Connections has a Replace button.

Replace the Stripe key: press Create key in Stripe for a new restricted key, paste it into Paste the new key and press Save. Do this if Stripe rejected the key, or to swap a full account key for a restricted one. The webhook stays as it is.
Replace the signing secret: press Open Stripe webhooks, copy the endpoint's signing secret (it starts with whsec_), paste it into Paste the signing secret and press Save. Do this if you rolled the secret or recreated the endpoint in Stripe. A recreated endpoint needs the URL and events above.

Test and live mode

A product is connected to one Stripe mode. There is no switch between test and live. To try Supaffi with Stripe test mode, create a separate product with a test key, starting with rk_test_. See Test your setup.