Connect Stripe to SamBooks for automatic invoices and receipts: a step-by-step guide

What it's for

Stripe is one of the most widely used systems to collect online payments: recurring subscriptions, one-off payments, checkout for SaaS and digital services. But Stripe only collects money: it does not issue Italian fiscal documents on your behalf.

When you connect Stripe to SamBooks, every payment that lands in your Stripe account is booked automatically with the right document:

• if the payer is a business with a VAT number (B2B), SamBooks reconciles the payment against the invoice you already issued;
• if the payer is a private consumer (B2C), SamBooks records the daily takings receipt (corrispettivo), splitting the VAT out of the amount collected;
• it works for both subscriptions and one-off payments.

You no longer have to export payments from Stripe and re-enter them by hand: you find them already recorded in SamBooks, ready for the VAT settlement.

Important: invoices and receipts remain SamBooks documents. Stripe is the collection channel; the fiscal document is always issued (or reconciled) inside SamBooks.

What you need

• An active Stripe account (the same one you use to charge your customers).
• Access to SamBooks as the company Manager (Gestore).
• Two "keys" you'll create on Stripe in a few minutes and paste into SamBooks:
  1. a read-only key (restricted key), with which SamBooks reads subscriptions, invoices and payments;
  2. a webhook signing secret, with which SamBooks confirms that the payment events really come from your Stripe account.

You paste both keys inside SamBooks: they must not be shared with anyone else, and they are stored encrypted.

Step-by-step (~5 minutes)

1. Open the connection panel in SamBooks

In SamBooks go to Settings → Company → Integrations and, on the Stripe card, click Connect. The connection window opens: keep it open — you'll need it to copy the webhook address and to paste the two keys.

2. Create the read-only key on Stripe

Open the Stripe dashboard at the API keys page: dashboard.stripe.com/apikeys. To try it first without moving real money, use test mode: dashboard.stripe.com/test/apikeys.

1. Click "Create restricted key".

2. Stripe asks "How will you use this key?" showing three cards: pick the first one, "Activate an integration you've built". (The other two — "Provide the key to a third party" and "AI agent authorisation" — are not needed.)

3. Under "Choose a permissions template" select "Create your own": this lets you set the exact permissions.

4. In the permissions table leave everything on None and set Read only on these four resources:

   Resource	Group	Permission
   Customers	Core	Read
   Invoices	Billing	Read
   Subscriptions	Billing	Read
   Prices	Billing	Read

   If you also collect one-off payments, you can add Checkout Sessions → Read: it improves recognition of direct payments. It's optional.

5. Name the key, for example "SamBooks (read-only)", and click Create key.

6. Copy the key that starts with rk_ — Stripe shows it only once — and paste it into SamBooks, in the Read-only key field of the connection window.

Is two-factor verification (2FA) required? In test mode no: Stripe lets you create the key without any verification. In live mode Stripe asks for 2FA when you create the key — keep this in mind when you move to real payments.

3. Configure the webhook on Stripe

The webhook is the "direct line" Stripe uses to notify SamBooks of every payment.

1. In SamBooks, in the connection window, copy the webhook address with the Copy button: it's an address unique to your company.
2. Open Stripe at the Webhooks page: dashboard.stripe.com/webhooks (in test: dashboard.stripe.com/test/webhooks) and click "Add endpoint".
3. In the Endpoint URL field paste the address you copied from SamBooks.
4. Under events to send select these four:
   • invoice.paid
   • invoice.payment_succeeded
   • checkout.session.completed
   • payment_intent.succeeded
5. Save the endpoint, then open it and copy the Signing secret that starts with whsec_.
6. Paste the whsec_ into SamBooks, in the Webhook secret field of the connection window.

4. Verify the connection

In SamBooks click Connect (or Verify). If the keys are correct the status turns to Connected and the window shows your Stripe subscriptions and invoices, read-only. From this moment every new payment is booked automatically.

What SamBooks does on each payment

• Payment from a business (B2B, with a VAT number): SamBooks looks for your invoice matching that payment and reconciles it (marks it as paid). If it finds no matching invoice, it records the payment as on hold (sospeso) and prompts you to match it or to issue the invoice.
• Payment from a private individual (B2C): SamBooks records the daily takings receipt (corrispettivo), splitting the VAT out of the amount collected. For online sales this receipt is exempt from electronic transmission to the Italian Revenue Agency: it still goes into the takings register and into the VAT settlement. An invoice to the consumer is issued only on request.
• Subscriptions and one-off payments: the mechanism is identical for recurring and single payments.

Italian tax code of consumers: Stripe does not transmit the Italian consumer's tax code (it only carries the VAT number, when present). If a private customer needs an invoice, the tax code must be collected separately.

Frequently asked questions

Do I have to create invoices on Stripe? No. Stripe is only for collecting money. Invoices and receipts are issued by SamBooks: that is what keeps you compliant with Italian tax rules.

Why a read-only key and not the full one? SamBooks only needs to read your payments, not change them. The read-only key is the safest choice, and the one Stripe recommends for sharing access.

Can I try it first with no risk? Yes: use Stripe's test mode (the /test/... links). Test keys start with rk_test_ and the webhook secret with whsec_; they move no real money.

I changed the key on Stripe: what do I do? Reopen Settings → Company → Integrations → Stripe, click Update credentials and paste the new key.

How do I disconnect Stripe? From the same window, the Disconnect button. Payments already booked stay; only the sync with Stripe stops.