Stripe integration
Integration setup
To set up the integration with Stripe through the user interface:
- In the side menu, select “Settings”;
- Select the “Integrations” tab;
- Click “Stripe” and enter your Stripe API key (locate your API key); and
- Click “Connect to Stripe” to confirm.
By default, customers created in Lago are not automatically created in Stripe. If you want your Lago customers to be added to Stripe, you need to activate this option (learn more).
Customer information
To collect payments automatically, the customer must exist in both the Lago and Stripe databases.
New customer
If the customer does not already exist in Stripe, you can first create them in Lago, either via the user interface or the API. When adding customer information, you must:
- Define Stripe as the default payment provider;
- Leave the field associated with the Stripe customer ID blank;
- Enable the option to automatically create the customer in Stripe; and
- Define payment method options for this customer. Possible values are
card
andsepa_debit
.
The customer will automatically be added to Stripe. Stripe will then return the customer ID, which will be stored in Lago.

Creation of a new customer with Stripe
Existing customer
If the customer already exists in Stripe but not in Lago, you should create the customer record, either via the user interface or the API. When adding customer information, you must:
- Define Stripe as the default payment provider;
- Provide the Stripe customer ID;
- Disable the option to automatically create the customer in Stripe; and
- Define payment method options for this customer. Possible values are
card
andsepa_debit
.

Migration of an existing Stripe customer
Payment methods
Lago’s direct integration with Stripe supports two native payment methods: Sepa Debits (SDD) and Card payments.
Dashboard
API
- Create or update an existing customer;
- Assign Stripe as payment provider; and
- Define payment method options: Card, Sepa Debit or both.
Note that Sepa Direct Debits are only available for invoices in EUR currency.

Payment method options available for Stripe native connection
Stripe Checkout: storing customer’s payment method information
Checkout page shows only selected payment methods for customers.
When Lago automatically creates a customer in Stripe, you will receive a checkout link from Lago to facilitate the storage of your customer’s payment method information.
The payload sent by Lago will have the following structure, with the checkout link stored under checkout_url
:
{
"webhook_type": "customer.checkout_url_generated",
"object_type": "payment_provider_customer_checkout_url",
"payment_provider_customer_checkout_url": {
"lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
"external_customer_id": "hooli_1234",
"payment_provider": "stripe",
"checkout_url": "https://checkout.stripe.com/c/pay/prod_c15sTbBMLep5FKOA9b9pZBiRBBYYSU1IJ5T89I5TTtpKgzE380JSmxnVYz#fidkdWxOYHw"
}
}
Note: The checkout link automatically expires after 24 hours!
By utilizing this provided checkout link, your customers can perform a pre-authorization payment. It’s important to note that the pre-authorization payment will not collect any funds from the customer. Once the pre-authorization is confirmed, Lago will send the payment method details and securely store them into Stripe for future transactions.
Default payment method
When you add a new payment method in Stripe, Lago automatically sets it as the default. This guarantees that Lago uses the latest payment method for a customer. However, if you manually designate one of multiple payment methods as the default, Lago will use it for payments instead the most recent one.
Payment intents
Once Stripe is connected and the customer exists in both databases, you can start collecting payments.
Each time a new invoice with an amount greater than zero is generated by
Lago, a payment intent will automatically be created. Stripe will record the
invoice ID and process the payment. If the payment is successful, the status of
the payment will switch from pending
to succeeded
.
If the payment fails, the status of the payment will switch from pending
to
failed
and Lago will generate an invoice.payment_failure
webhook.
A valid payment method for the customer must be defined in Stripe for the payment intent to succeed (learn how to save payment details).