> ## Documentation Index > Fetch the complete documentation index at: https://vida.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Stripe Billing Integration > Stripe Billing Integration and Configuration Stripe is a subscription billing and revenue management platform built for businesses offering recurring, SaaS-based, or usage-based pricing models. Vida integrates with Stripe to enable your Agent product plans to work seamlessly with Stripe's subscription system. This allows you to create and manage monthly subscriptions based on your Vida plans. ## Preparing for configuration This integration is available to eligible reseller and partner accounts that bill downstream customers. Before starting, confirm the Vida account that will own the billing connection and note its account ID. * Resellers use their reseller account ID in the Stripe webhook URL. * Partners use their partner account ID in the Stripe webhook URL. Keep these values available for the final Vida connection step: * Stripe secret API key * Stripe publishable key * Webhook signing secret * Product ID for each Agent plan * Price ID for each Agent plan You can connect the provider through the [Billing Provider API guide](/docs/api-reference/platform-guides/billing-providers). If your account does not have access to billing-provider configuration, contact Vida. ## What the integration covers * Creating new subscriptions through Stripes hosted checkout * Cancelling subscriptions * Subscription renewals * Upgrading / Downgrading Plans in a subscription * Adding usage overages to pending invoices * Creating a secure portal session between your customers and Stripe for managing payment methods and invoices * Account activation based on subscription activation and successful payment * Create new customer in Stripe if they don't exist * Will use existing customer if we find one based on email address ### New subscriptions Through your Vida reseller portal, customers can subscribe to your Agent product plans and be redirected to Stripe's secure hosted checkout. This collects the customer's payment information and creates a new subscription under the Stripe customer profile. If the payment succeeds, Stripe will inform the Vida platform the account is paid and apply the requested plan. If the Stripe customer already has active subscriptions for other products, Vida creates a separate subscription so those subscriptions remain unchanged. ### Cancelling subscriptions Subscriptions can be cancelled by a few different methods: * Customer disables their account on the Vida platform * Customer cancels their plan through the Vida billing settings * You cancel the subscription manually through Stripe * Stripe is set to automatically cancel the subscription if payment is uncollectible after the payment retry period. ### Subscription Renewals Stripe manages subscription renewals. By default, Vida subscriptions renew on the anniversary day of their creation. When a subscription renews, Stripe tells Vida that a new billing cycle has begun so Vida can display the current and previous billing-period ranges. ### Upgrading or Downgrading Plans When a customer wants to upgrade or downgrade their Agent plan, Vida automatically switches the plan in the existing subscription. On upgrades, Stripe will charge the prorated amount of the new plan immediately to bring the balance where it should be. On downgrades, Stripe may be configured to credit customer account the amount instead of refunding. This would be applied on the next billing cycle. ### Adding usage overages to pending invoices As a customer's usage progresses through the month, when the next billing cycle happens, we will grab the usage from the previous billing period (previous month) and determine if any usage overages are due. Overages are any product items you have configured for their plan and they have consumed an amount that exceeds any included amount. These charges are then pushed to Stripe's pending invoice so payment can be collected. ## Configure Stripe and Connect It to Vida This section covers configuring Stripe to prepare for the integration with Vida. We'll be covering: * Creating the Product Plans and Pricing * Enabling Hosted Checkout * Enabling Customer Portal (Payment Method Management and Invoices) * Configuring Webhooks to Vida platform * Creating API Keys * Configure Failed Payment Settings ### Creating the Product Plans and Pricing After creating your Agent product plans in Vida, create the corresponding products and prices in Stripe. Record each Stripe product ID and price ID so the matching Vida plan can be connected to it. \ \ In your Stripe account: 1. Navigate to \*\*Product Catalog \*\*and click "+**Create product** " button In the Add a product screen: * **Name**: This should match the plan name you provided in your Vida Agent plan * **Description**: This is a friendly description that your customers will see on the checkout screen * Click "**Recurring**" box right above amount * Set the **Amount** to the plan's dollar amount that matches the amount you have set on the Vida agent plan * **Billing Period**: Set to "**Monthly**" * Click "**Add Product**" button to create the product plan * Note: Vida does not provide any tax advice on how to charge taxation to your products. * After you click create, we will need to collect both the **product Id** and the **price Id** \ 3\. This will bring you to the Product Catalog screen. Grab the product Id and the Price Id for the plan. Click on the product you just created. * The product Id is on the right under **Details**. Click the copy button to get the product Id associated with this plan. * The price Id can be obtained by clicking the "**...**" next to the price in the **Pricing** section and click "**Copy price id**" * Repeat these steps for any other agent products you created with Vida. Provide both the Product Id and the Price id to the Vida team to complete the agent product plan configuration. ### Enabling Hosted Checkout Vida uses Stripe's hosted checkout when customers choose an initial plan in the Agent platform. Hosted Checkout is enabled by default. But you may want to customize the Checkout screen to give your branding (logo, etc). 1. Open settings, then select **Business → Branding → Checkout & Payment Links**. Vida uses embedded checkout by default, but you should review both the hosted and embedded branding. ### Enabling Customer Portal (Payment Method Management and Invoices) \ Vida uses Stripe's customer portal feature to allow user's to securely manage their payment methods and view invoices. This is not enabled by default. 1. To enable the Customer Portal feature, navigate to **Settings (Gear Icon) -> Billing -> Customer portal tab**. 2. Under **Invoices**, toggle **Invoice history** to enabled 3. Under **Customer information**, enable the attributes customers should be able to change. 4. Under **Payment methods**, enable **Payment methods** 5. Under **Cancellations**, it's recommended to toggle this to disabled and allow them to only cancel through your Vida reseller portal. 6. Under **Subscriptions**, it's recommended to disable these settings if possible to avoid allowing them to switch plans/quantity to a product not configured on Vida. 7. Under **Business Information**, these items are optional. Vida's platform will handle all the Redirect link when it creates portal sessions. 8. Click **Save Changes**. ### Configuring Webhooks to Vida platform Lastly, let's configure the communication link between Stripe and Vida. This will allow Vida to receive the events from Stripe when payments or subscription events occur. 1. Click on the \*\*Developers \*\*button on the bottom left of the portal. 2. Click on the **Webhooks** tab then click **+ Add endpoint** button 3. **Endpoint URL for a reseller**: `https://api.vida.dev/stripe/events?resellerId=YOUR_RESELLER_ACCOUNT_ID`\ **Endpoint URL for a partner**: `https://api.vida.dev/stripe/events?partnerId=YOUR_PARTNER_ACCOUNT_ID` 4. Set **Listen to** to the **Events on your account** 5. Set **Version** to **2020-08-27** 6. Click the **+ Select events** button. Vida requires the following events: checkout.session.completed charge.succeeded charge.failed customer.updated customer.subscription.deleted customer.subscription.updated customer.subscription.created invoice.payment\_failed invoice.overdue invoice.paid invoice.marked\_uncollectible invoice.created\ **(12 events total)** 7. Click **Add endpoint** button to finish the configuration 8. After the endpoint is added, obtain the webhook signing secret by clicking on the new endpoint and selecting **Reveal** under **Signing secret**. Use it in the Vida connection step. ### Creating API Keys Lastly, we need to configure the API keys (API Key and PublishableKey) so that Vida can connect to your Stripe instance. 1. Navigate to **Developers** in the bottom right of the portal 2. Click **API Keys** tab 3. By default, Stripe creates a **Publishable key** and a **Secret key**. Use both keys, together with the webhook signing secret, when you [connect Stripe to Vida](/docs/api-reference/platform-guides/billing-providers). ### Configure Failed Payment Settings Stripe handles collection after an invoice payment fails. You can configure how long an account remains past due and how often Stripe retries the payment. \ \ This is also where you decide what happens after all retries are exhausted. For example, Stripe can cancel the subscription, which tells Vida that the account is unpaid and can remove access to paid resources. Choose settings that match your collection and customer-support policies.\ \ To configure the Failed Payment settings, go to **Settings (Gear Icon) -> Billing -> Subscription and emails tab**. * **Prevent failed Payments** * Enable **Send emails about expiring cards** with **Link to a Stripe-hosted page** * **Manage failed payments for subscriptions** * Select **Use a Smart Retry Policy for subscriptions** and Retry up to **8 times** within **2 weeks** * Enable **Send emails when card payment fail** with **Link to a Stripe-hosted page** * Set **If all retries for a payment fail** to **cancel the subscription** * Set **If all retries for a payment fail** to **mark the invoice as uncollectible** * **Manage invoices sent to customers** * Enable **Send finalized invoices and credit notes to customers**\ \ Ensure to hit **Save** for each section where you have made changes.