Chargebee is a subscription billing and revenue management platform built for businesses offering recurring, SaaS-based, or usage-based pricing models. It integrates with multiple payment gateways, including Stripe and Authorize.net, to securely process payments.

Vida integrates with Chargebee to enable your Agent product plans to work seamlessly with Chargebee’s subscription system. This allows you to create and manage monthly subscriptions based on your Vida plans.

​
Preparing for configuration

Before starting your Chargebee configuration, make sure you obtain the following information from the Vida team prior:

  • Your Reseller Id (Used for configuring the webhook URL)

While this document covers setting up your Chargebee environment, at this end of this configuration, you will be providing the Vida team with the following information:

  • API Key
  • PublishableKey
  • Site
  • Product Plan Id (per agent plan)
  • Price Id (per agent plan)
  • webhookUsername
  • webhookPassword

​
What the integration covers

  • Creating new subscriptions through Chargebee 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 Chargebee for managing payment methods and invoices
  • Account activation based on subscription activation and successful payment
  • Create new customer in Chargebee 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 redirect to Chargebee’s hosted checkout session (secure checkout). This will collect the customer’s payment information and create a new subscription under the Chargebee customer profile.

If the payment succeeds, Chargebee will inform the Vida platform the account is paid and apply the requested plan.

Note: If the customer account in Chargebee already has other active subscriptions for your other products, Vida creates a new subscription as to not interfere with your policies on that subscription. For instance, the Vida platform tells Chargebee to create pending invoices for it’s subscription allowing Vida to append usage charges to the invoice before payment.

​
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 Chargebee
  • Chargebee is set to automatically cancel the subscription if payment is uncollectible after the dunning period.

​
Subscription Renewals

Chargebee manages the subscripton renewals itself. By default, Vida subscriptions renew on the anniversary day of when the subscription was created. If a subscription was created on April 5th, then the subscription will renew on May 5th. When the subscription renews, Chargebee informs the Vida platform a new billing cycle has begun which allows Vida to provide current and previous billing period ranges on our usage screens.

​
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, Chargebee will charge the prorated amount of the new plan immediately to bring the balance where it should be. On downgrades, Chargebee 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 Chargebee’s pending invoice so payment can be collected.

​
Configurating Chargebee and Connecting to Vida

This section covers configuring Chargebee to prepare for the integration with Vida. We’ll be covering:

  • Creating the Product Plans and Pricing
  • Enabling Hosted Pages (Checkout screens)
  • Enabling Self Service Portal (Payment Method Management and Invoices)
  • Automated Metered Billing Settings
  • Configuring Webhooks to Vida platform
  • Creating API Keys
  • Getting your Site value
  • Configure Dunning Settings

​
Creating the Product Plans and Pricing

After you have already worked with the Vida team to create your agent product plans (agent plan creation and management coming soon to the reseller portal!), we will need to create the product plans and pricing in Chargebee. We’ll then need to take the product plan Id and price Id and configure it on your agent product plan in the Vida platform.

In your Chargebee account:

  1. (Skip this step if you have your own product family you’d like to use) Navigate to Product Catalog -> Product Families -> ”+ Create Product Family” button. Product families are used to bucketize product plans and add-ons to be used together.

  2. Enter a Product family name and description and click “Create” button on top right. Example:




    3. Create the product plan by navigating to Product Catalog -> Plans -> ”+ Create Plan” button.

    • Product Family: Select the previously created Product Family or the family you wish to use.\

    • External Name: This should match the plan name you provided in your Vida Agent plan\

    • Internal Name: This is Chargebee’s internal plan name and will be used to generate the Plan Id.

    • This plan is metered - Leave this box Unchecked

    • Display in Self-Serve Portal - Leave this box Unchecked as we do not want to allow plan switching in Chargebee portal, only through the Vida platform.

    1. After you click “Create” you will be brought back to the product plans overview screen. Here we will set the price

    • Under pricing section, click “Set Price” next to the Monthly frequency line. This will bring you to the screen to set the monthly price.

    • Pricing Model: Set this to Flat Fee

    • Price: set this to the USD value that you have configured on your Vida Agent plan\

    • Billing Cycles: Set this to forever to keep the subscription ongoing until either you or your customer cancels.

    • Click Create button on top left

    1. After you click create, we will need to collect both the plan Id and the price Id

    • The product plan Id can be found in the top section of the product plan.

    1. Fetch the Price Id by going onto the Plan’s Pricing section and clicking on “Monthly” on the price line you just updated


    7. This will bring you to the Price configuration screen where we can get the price Id. Click the copy icon to the right of the ID.

    1. Repeat these steps for any agent product plans you created with Vida. Provide both the Product Plan ID and the Price Id to the VIda team to complete the agent product plan configuration.

​
Enabling Hosted Pages (Checkout)

Vida uses Chargebee’s hosted pages for checkout when customers choose an initial plan in the Agent platform. To enable:

  1. Navigate to Settings -> Configure Chargebee -> Customer-Facing Essentials Section -> Checkout and Self-Serve Portal
  2. Click the Configuration tab at the top right
  3. Under the checkout section:
  • Identify existing customers for checkout access using: Set to Single Sign On API

​

​
Enabling Self Service Portal (Payment Method Management and Invoices)


In the same configuration screen, navigate to the Self-Service Portal section.

  1. On the setting Customers can access the self-serve portal setting is set to Via Single Sign On API. This allows the Vida platform to create portal sessions for your customers to securely manage payment methods and view invoices.

​
Automated Metered Billing Settings

The Vida platform will leverage pending invoices on the subscriptions it manages to append usage charges before the invoice is finalized. Let’s configure the settings for this to describe how Chargebee should handle and automatically close these invoices.

  1. Navigate to Settings -> Configure Chargebee -> Billing Section -> Billing LogIQ -> Billing & Invoices -> Metered Billing
  2. Click Enable on the bottom of the screen. Configure each setting as below:
  3. Click Apply button on the top right of the screen.

​
Configuring Webhooks to Vida platform

Lastly, let’s configure the communication link between Chargebee and Vida. This will allow Vida to receive the events from Chargebee when payments or subscription events occur.

  1. Navigate to Settings -> Configure Chargebee -> API Keys and Events Section -> Webhooks\
  2. Click ”+ Add Webhook” button
  1. Toggle “Protect webhook URL with basic authentication” to On.
  2. Configure the Username and Password to something that is secure
  3. Set API Version to “Version 2”
  4. Set this as primary should be toggled to On. If you have an existing webhook that is primary, please let Vida know as this may impact the integration.
  5. IMPORTANT STEP: Click the “Events to Send” box and configure the below events:
  • Customer Changed
  • Subscription Created
  • Subscription Activated
  • Subscription Changed
  • Subscription Cancelled
  • Subscription Renewed
  • Pending Invoice Created
  • Pending Invoice Updated
  • Invoice Generated
  • Invoice Updated
  • Invoice Deleted
  • Payment Succeeded
  • Payment Failed

    (13 total event types)

​
Creating API Keys

Lastly, we need to configure the API keys (API Key and PublishableKey) so that Vida can connect to your Chargebee instance.

  1. Navigate to Settings -> Configure Chargebee -> API Keys and Events section -> API Keys
  2. Click ”+ Add API Key” button
  3. Choose “Full-Access Key”
  4. Choose “All”
  5. Set the name of the API Key to “Vida”
  6. Click Create Key button\
  7. After creation, this will take you back to the key list. Find the Key you just created with the name of Vida and click the copy icon next to the key value. Give this to your Vida contact. \
  8. In this same list, you should also see a key called “publishable_api_key” or similar. Also copy this key and provide to Vida to complete the configuration.

​
Getting your Site value

Your Chargebee site tells Vida where to connect to your platform. This is located in the URL of your browser session and also in the top left corner of Chargebee dashboard. By default, Chargebee gives you a production site and a test site. You will need your Production Site value to configure with Vida.

For instance, if you are logged into your production Chargebee account at https://acmesolar.chargebee.com, your site value would be “acmesolar”.

​
Configure Dunning Settings

Chargebee’s dunning feature allows you to configure how Chargebee will handle collection of payment after an attempted payment of an invoice failes. You can configure how long an account remains in a dunning state and how often Chargebee tries to re-attempt the payment.

Here is where you also configure what Chargebee does with the subscription when it has exhaused all retries. For instance, if all payment retries have failed, you may want Chargebee to automatically cancel the subscription. This would trigger the Vida platform to put the account in an unpaid state and release all of the phone numbers from the agents. Vida recommends this if you do not want to manage the collection itself and wish your customer’s agents to be shutdown if payment can not be collected.

To configure the Dunning settings, go to Settings->Configure Chargebee -> Dunning for online/offline payments.

If you wish for Chargebee to cancel the subscription after all payment reattempts have failed, configure the “When dunning period ends, what happens to subscriptions” setting to “Cancel Subscriptions”. Click Apply button.

Also, review the Dunning period duration and the Retry Frequency to best suit your business needs.