Integrations ยท Payment providers
Stripe sales, each tied to the visit that brought the buyer.
Connect Stripe with a restricted key that can only read. Tally imports your past 365 days, then takes each payment as it happens, and links it to a visitor by the strongest evidence it has.
14 days free, no card needed.
01What Tally reads
- Every payment once, by its PaymentIntent, whatever made it: Checkout, a Payment Link, an invoice or a PaymentIntent your code created.
- Subscriptions told apart by the invoice: a first payment, a renewal, or a plan change; a trial that converts counts as a sale.
- Refunds, partial ones too, and chargebacks: funds withdrawn as negative, funds reinstated as positive.
- Amounts without tax, in US cents at the European Central Bank's rate for the payment's day, with zero-decimal currencies counted correctly.
- The past 365 days when you connect, then each payment within seconds through a webhook endpoint Tally creates on your account.
02How a sale finds its visit
- Checkout metadataYour code passes the visitor's id as tally_visitor_id in the Checkout Session's metadata, and in subscription_data.metadata so renewals follow. High confidence.
- Payment LinksThe snippet adds the visitor's id to buy.stripe.com links as client_reference_id on its own, in cookie mode and in consent mode after consent. High confidence.
- Success pageYour success URL carries ?session_id={CHECKOUT_SESSION_ID}, and the visitor who saw that page first is the buyer. High confidence, and it works in cookieless mode.
- EmailYour site calls tally('identify', { email }) and the payment's customer email matches it, both hashed. Medium confidence.
- Renewals and refundsA renewal or upgrade takes the link of the subscription's first payment; a refund or chargeback takes the link of the payment it reverses.
03What it can't read
- Payments made with the legacy Charges API, which have no PaymentIntent, aren't counted, and neither are their refunds or disputes.
- Invoices paid outside Stripe, marked paid by hand, or settled from a credit balance move no money in Stripe, so they're not counted.
- A Stripe account feeds only one site at a time; connecting it to a second site is refused until it's disconnected from the first.
- Dispute fees are a cost, not revenue, so they're not counted as a chargeback.
04Connecting it
- In Stripe, open Developers, API keys, choose Create restricted key, and set the permissions below. Leave everything else at None.
- Paste the key on your site's Integrations page. Each permission is checked with a real call, so a missing one is named before anything is stored.
- Tally seals the key, creates its own webhook endpoint on your account, and imports the past 365 days.
- For high-confidence links on Checkout Sessions your code creates, the Coverage page gives the lines to add, for Node, Next.js, Python, Ruby and PHP.
What the restricted key needs
Tally asks for a restricted key that can do only this, and checks each permission with a real call when you paste it, so a missing one is named:
| Permission | Access | Why |
|---|---|---|
| PaymentIntents | Read | Every payment: its amount, currency, customer and metadata. |
| Invoices | Read | Whether a payment is a subscription's first, a renewal or a plan change, and the tax in it. |
| Checkout Sessions | Read | The visitor id you pass in metadata or client_reference_id, and which Payment Link sold it. |
| Customers | Read | The customer's metadata, and their email to match tally('identify'): hashed at once, never stored. |
| Charges | Read | Refunds. |
| Disputes | Read | Chargebacks, and funds reinstated after a won dispute. |
| Webhook Endpoints | Write | Tally creates its own endpoint on your account, so payments arrive within seconds. |
Where to make it: Stripe, Developers, API keys.
05Questions
Why a restricted key and not my secret key?
A restricted key can do only what you allow. Tally needs to read payments and create one webhook endpoint, never to move money, and you can revoke the key in Stripe at any time. A secret key is refused.
Do renewals keep the source of the first sale?
Yes. A renewal or upgrade takes the link of the subscription's first payment, so recurring revenue stays with the visit that won the customer. Put the visitor's id in subscription_data.metadata too, and every renewal carries it.
Does test mode work?
Yes. A test-mode restricted key connects like a live one, and the integration shows a test-mode badge, so you can try the whole flow with Stripe's test cards first.
What about payments in other currencies?
Each is converted to US cents at the European Central Bank's reference rate for its day. A currency the ECB doesn't publish is kept in its own amount and flagged rather than given an invented rate.