Self-Serve Portal Integration Options

Chargebee offers the following options to integrate the Hosted Self-Serve Portal, depending on your application or website's framework and business model:

• API (recommended if you authenticate users in your own application)
• Drop-In Script

The Hosted Self-Serve Portal displays as a modal popup or as a standalone page. Do not embed hosted portal URLs in your own iframe elements. Use Chargebee.js to open the portal as a modal, or redirect customers to the standalone portal page.

When to use API vs. Drop-In Script

Use the API if you authenticate users in your own application. Use the Drop-In Script if you do not have a user authentication system and rely on Chargebee to authenticate customers.

API-based integration

Chargebee supports single sign-on (SSO) to access the Self-Serve Portal. If you have your own mechanism for authenticating users, use Chargebee's SSO capability to give customers portal access for managing billing and subscription details.

The API-based integration workflow looks like this:

For details, see the Portal Sessions API.

Call flow

Host an HTTPS endpoint that calls the Chargebee portal session API and returns a portal session object.

Your application then uses Chargebee.js to open the Self-Serve Portal.

Before you call the methods in this section, set up Chargebee.js and initialize a Chargebee instance.

Set the portal session

Pass a function to setPortalSession() that returns a promise resolving to a portal session object.

cbInstance.setPortalSession(function() {
  return $.ajax({
    url: '/create_portal_session',
    method: 'POST',
    data: data
  });
});

Open the Self-Serve Portal

Create the portal object and open it.

let cbPortal = cbInstance.createChargebeePortal();
cbPortal.open({
  close() {
    // Close callback
  }
});

To open the portal directly at a specific section, such as subscription details or billing history, see openSection() in the Chargebee.js Reference.

Log the customer out

After a customer accesses the Self-Serve Portal, Chargebee maintains the session for one hour. To end the session earlier, call logout() on the Chargebee instance.

Create a portal session on your server

1. Create an HTTP endpoint on your server.
2. Create the portal session using the portal session API.
3. Return the portal session object to the client.

post 'create_portal_session' do
  customer_id = params[:customer_id] # Fetch the customer ID from your own session.
  result = ChargeBee::PortalSession.create({
    :customer => {
      :id => customer_id
    }
  })
  return result.portal_session.to_s
end

The endpoint returns a portal session object:

{
  "id": "portal_XpbGElGQgEHspHB",
  "token": "<portal-session-token>",
  "access_url": "https://yourapp.chargebeeportal.com/portal/access/<portal-session-token>",
  "status": "created",
  "created_at": 1515494835,
  "expires_at": 1515498435,
  "object": "portal_session",
  "customer_id": "XpbGEt7QgEHsnL7O"
}

Drop-In Script integration

The Drop-In Script integrates the Hosted Self-Serve Portal into your website without custom code. Use it only if you do not have a user authentication system and rely on Chargebee to authenticate customers.

The Drop-In Script workflow looks like this:

To generate the portal button code, click Settings > Configure Chargebee > Checkout and Self-Serve Portal > Integrate with Chargebee. Copy the generated snippet and embed it in the portal button on your website, as shown on the <a> element in the following example.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script
      src="https://js.chargebee.com/v2/chargebee.js"
      data-cb-site="acme-test"
    ></script>
  </head>
  <body>
    <a href="javascript:void(0)" data-cb-type="portal">Open customer portal</a>
  </body>
</html>

Single account vs multiple account login

In Chargebee, an email address can be linked to customer accounts in two ways:

• Single account: An email address dedicated to one customer account.
• Multiple accounts: An email address shared by multiple customer accounts.

After the accounts are created, customers can log in and use the Self-Serve Portal. The login experience differs for these two scenarios.

Single account login

When an email address belongs to one customer account, the login flow has no account selection page. The customer enters the email address and then the one-time password (OTP) they receive to log in to the Self-Serve Portal.

Multiple account login

When multiple customer accounts share one email address, the login flow includes an account selection page (step 3 of the login flow) where the customer selects the account to log in to the Self-Serve Portal with. This page fetches all the accounts linked to the entered email address, and you can view them as you scroll down the page.

The login flow looks like this:

1. Enter your email address and click Continue.

   

2. Enter the one-time password received on your email address.

   

3. The account selection screen appears. Scroll down, locate the relevant account and select it to access the Self-Serve Portal.

   

4. After selecting the relevant account, you can view the Self-Serve Portal for the selected account.

   

Display additional information for the accounts

By default, on the account selection page, the accounts are distinguished by a # number along with the Signed up on date. This doesn't provide enough details to help the customer select the correct account to log in to.

You can add more information like First Name, Last Name, Company, and more to the account tabs by using an existing label.

Follow these steps to configure the label for your accounts:

1. In your Chargebee app, go to Settings > Configure Chargebee > Checkout & Self-Serve Portal.

2. Select the Labels tab and click Add more copy/text.

   

3. Search for additional, click the + icon next to the Additional Information label, and then click Add.

   

4. Click the edit icon next to the newly added label in the list.

   

5. In the Configuration for Additional Information box:

   • Press the space bar once, click the + button, and select the field from the list that you want to add.
   • To add another field next to the previous one, press the space bar on your keyboard again, click the + button and select the field.
   • To end the current line and add a new field to the next line, write {space}EOL{space} and add the field that you want to add after it. Note that {space} indicates leaving a space before and after EOL.
   • Click Apply.

6. Click Publish.

   

Restart the login flow to see the additional information on the account selection page.