Connect Paddle

Why Paddle

Paddle is a merchant of record. It is the legal seller of whatever you sell, which means it collects and remits sales tax and VAT in every jurisdiction your customers are in. You never register for VAT anywhere.

That is the whole trade: roughly 5% + 50¢ instead of Stripe's 2.9% + 30¢, in exchange for never thinking about tax again.

Before you start

Paddle approves sellers individually and will look at your website before switching your account on. Do that first — the keys below exist before approval, but payments will not go through until Paddle has said yes.

Where to get the three values

All three live in Paddle → Developer tools.

Paddle API key — Developer tools → Authentication. Create a key with write access to Products, Prices and Transactions.

Paddle client-side token — the same Authentication page, Client-side tokens section. This is a different, deliberately public token; it is what opens the checkout in your customer's browser. Safe to expose, unlike the API key.

Paddle webhook secret key — Developer tools → Notifications. Add a destination pointing at the webhook URL kitty gives you (see below), then copy the secret key it generates for that destination.

Order of operations that saves a round trip: connect with the first two values, copy the webhook URL from the card, set up the notification destination in Paddle, then come back and Replace keys with all three filled in.

Connecting

Settings → Connections → Take payments → the Paddle card → Connect → fill the fields → Save and connect.

The webhook, which is not optional

kitty needs Paddle to tell it when someone pays. Without that, the checkout takes the money and no order, customer or revenue figure ever appears in kitty.

On the connected card, press Webhook URL, copy it, and paste it into Paddle → Developer tools → Notifications as a new destination.

Treat that URL like a password — anyone holding it can post events at this venture. It never expires; you rotate it by disconnecting and reconnecting. Deliveries are capped at 300 a minute per venture.

How Paddle checkout looks to your customer

Unlike most providers here, Paddle has no page to send someone to. Its checkout opens as an overlay on kitty's own pay page, drawn by Paddle in its own frames. Your customer never leaves, and card details still go straight to Paddle.

What you get

One-off sales and subscriptions, failed-payment recovery, refunds issued from kitty, and sales tax handled for you.

After it's connected

Test connection proves the key works right now, and names the account it reached — so a member with two logins can see they pasted the wrong one. Do that before you put anything on sale.

Then, in Where new checkouts go, pick this provider on its own or One page, every method, which offers every provider you've connected on a single page and quietly hides one that starts failing.

Anything already on sale keeps the provider it was armed on. A price, once created at a provider, cannot be moved — so to switch, open the venture's Revenue tab, Take off sale, then put it back on sale.

How the keys are stored

Encrypted at rest with AES-256-GCM, used server-side only, never returned to the browser, never written to a log, and never shown again after saving.

Payment keys are scoped to a venture or the whole workspace, never to you personally — two businesses in one workspace settle into two different bank accounts, so a personal key is refused for money on purpose.