Stripe permissions needed for a restricted API key with Lago

If you want to connect the Stripe integration without issuing a full-access secret key, Lago works with a restricted key scoped to seven resources. Six of them need Write access and one needs only Read, because Lago actively creates and updates Stripe objects throughout the payment lifecycle rather than just reading them.

Permissions to grant

When creating a restricted key in Stripe, set the following:

• Customers: Write

• Payment Intents: Write

• Payment Methods: Write

• Refunds: Write

• Checkout Sessions: Write

• Webhook Endpoints: Write

• Events: Read

A read-only key, or one missing any of the Write resources above, will silently break payment collection or webhook registration, so grant the full set.

Why each permission is needed

Each resource maps to a specific action Lago performs in Stripe:

• Customers (Write): Lago creates and syncs a Stripe customer record for each of your Lago customers so payments are attributed correctly.

• Payment Intents (Write): Lago triggers payment collection for invoices by creating payment intents against your customers' saved payment methods.

• Payment Methods (Write): Lago reads, saves, and removes payment methods on your customers' Stripe profiles, for example when they add or change a card.

• Refunds (Write): Lago initiates refunds in Stripe when you issue a credit note.

• Checkout Sessions (Write): Lago uses Stripe Checkout to let customers securely enter and save their payment details.

• Webhook Endpoints (Write): Lago registers its own webhook URL in your Stripe account so it can receive real-time payment status updates.

• Events (Read): Lago polls Stripe events to stay in sync with payment status changes, which only requires read access.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.