Stripe

1. 1

   Stripe Dashboard → Developers → API keys → Create restricted key

2. 2

   Set Read on: Checkout Sessions, Invoices, Subscriptions, Charges (includes refunds)

3. 3

   Optional: Write on Webhook Endpoints, so we can register the webhook for you

4. 4

   Create the key and paste it here (rk_live_… or rk_test_…)

Direct link: dashboard.stripe.com/apikeys/create

1. 1

   Open your site's Settings → Revenue (owners only) and click Connect next to Stripe.

2. 2

   Paste the restricted api key, then click Connect Stripe. Trakily checks the key and tells you exactly which permissions are missing, if any.

3. 3

   The first sync imports your full history in the background. After that, Trakily pulls changes every 15 minutes, and webhooks deliver new payments within seconds.

Keys are encrypted at rest and only used to read payments. Test-mode and live keys both work; a test key only sees test data.

Trakily registers the webhook in your Stripe account for you when you connect, as long as the key allows it. The webhook card in Settings then says Registered automatically. It stays in your Stripe account; delete it there if you disconnect.

Prefer to add it yourself? Tick I'll register the webhook myself when connecting, then create an endpoint in Stripe with the URL shown in Settings and these events, and paste its signing secret into the webhook card:

https://trakily.com/api/webhooks/stripe/pls_…

On your server, read the ids from Trakily's cookies and add them when you create the Checkout Session. Trakily reads metadata.trakily_visitor_id and metadata.trakily_session_id. If you only set client_reference_id, it is used as the visitor id as long as it looks like one (12–64 letters and digits).

// Read Trakily's ids on your server (Next.js example)
import { cookies } from "next/headers";
const jar = await cookies();
const visitorId = decodeURIComponent(jar.get("_trakily_vid")?.value ?? "").split("|")[0];
const sessionId = jar.get("_trakily_sid")?.value ?? "";

await stripe.checkout.sessions.create({
  // …your line items, mode, success_url
  success_url: "https://yoursite.com/thanks?session_id={CHECKOUT_SESSION_ID}",
  client_reference_id: visitorId,
  metadata: { trakily_visitor_id: visitorId, trakily_session_id: sessionId },
});

The keys are always trakily_visitor_id and trakily_session_id. The visitor id is the first part of the _trakily_vid cookie (before the first |); the session id is the _trakily_sid cookie. If the session id is missing, Trakily uses the visitor's latest session before the payment.

Include session_id={CHECKOUT_SESSION_ID} in your success_url as in the example. Stripe replaces the placeholder with the real id (it starts with cs_), and the script on your thank-you page reports it. Using Payment Links? Set the confirmation page to redirect to your site with the same parameter.

• “That doesn't look like a Stripe key.” Use a restricted key starting with rk_live_ or rk_test_.
• “This key is missing permissions: …” Edit the restricted key in Stripe and add Read access to the resources listed.
• Webhook not registered automatically. The key doesn't have Write on Webhook Endpoints. Add it and reconnect, or add the webhook by hand.
• Payments arrive but show as unattributed. Pass the visitor id at checkout (step 4). Payments that can't be matched yet are retried every hour for 90 days, so a later identify call can still link them.
• Nothing new since connecting. Click Sync now on the provider card. If the card says Needs attention, the error message tells you what the provider returned (for example a revoked key).