Settings
Configure SDK
Portal sessions
Customer Portal lets your customers to manage their account and billing themselves. Chargebee supports Single Sign-on (SSO) to access the customer portal. If you already have your own authentication for your website, it allows your authenticated customers to access their portal without having to login again.
Note: You can instead allow your customers to access the portal via login page provided by Chargebee. Read more.
Please follow the below steps for supporting portal access via SSO:
- Enable the "Allow access to customer portal via API" under "Settings > Hosted Pages Settings > Customer Portal" to use the portal sessions API.
- Provide a link in your website/application which your authenticated customers can use to access the portal (For example,
{your_website_url}/portal_link). - Handle the link request in your server code and create a portal session for the customer by calling Chargebee's "Create a portal session" API
- Forward the user to the access URL present in the "Portal Session" resource returned by the above API call.
Notes about access URL:
- The access URL should be accessed by the customer within one hour from the time it was created.
- Once accessed, the session is valid until the user logs out from the portal UI or logout API is called from your application for this session.
- Once accessed, the access url cannot be reused. Hence do not persist this URL. Whenever you need to provide access to the portal, you need to create a new portal session.
Using Chargebee's authentication to allow access to your website
Note: This feature is not supported in in-app portal.
Chargebee allows you to integrate your website by building user authentication on top of Chargebee. If you would want to allow access to parts of your website only to subscribers (like a paywall), you can integrate Chargebee's authentication without having to handle it from your end.
Workflow:
Users should be redirected to the portal login URL - https://yourdomain.chargebeeportal.com/portal/login by passing the following parameters:
- return_url - URL the users should be redirected to upon successful authentication.
- cancel_url - URL the users should be redirected to when they want to go back to your website during login. The domain name used in the Return/Cancel URL should be added as a 'Whitelisted Domain' in Chargebee. Add just the domain name in Chargebee and not the entire URL: E.g. yourdomain.com.
Upon successful authentication, a session is created for the user and Chargebee redirects the user to the return_url along with the following parameters:
- auth_session_id - Identifier to the authenticated session.
- auth_session_token - Token for the session which should be sent later to activate this session. Using the auth_session_id & auth_session_token, you should call Activate a Portal Session API to validate the session details and create a session for that user in your website. Note: The process of setting up the portal account will take place along with the authentication process.
Sample portal session [ JSON ]
{
"access_url": "https://yourapp.chargebeeportal.com/portal/access/__test__Lu9rnqItHAdfpSIyeyTbi1YYIxBCc2dq",
"created_at": 1517506765,
"customer_id": "__test__5SK0bLNFRFuCK5OOQ",
"expires_at": 1517510365,
"id": "portal___test__5SK0bLNFRFuCK5rOS",
"linked_customers": [
{
"customer_id": "__test__5SK0bLNFRFuCK5OOQ",
"has_active_subscription": false,
"has_billing_address": false,
"has_payment_method": false,
"object": "linked_customer"
}
],
"object": "portal_session",
"redirect_url": "https://yourdomain.com/users/3490343",
"status": "created",
"token": "__test__Lu9rnqItHAdfpSIyeyTbi1YYIxBCc2dq"
}The list of customers for this session
Create a portal session ¶
Creates a portal session for a customer. The session resource in the response contains the access URL. Forward the customer to that access URL. If you would like to logout the customer later via API call, you need to store the id of the portal session resource returned by this API. While creating a session, you also need to pass the redirect URL to which your customers will be sent to upon logout from the portal UI.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing portal_session
Retrieve a portal session ¶
This API retrieves a portal session using portal_session_id
as a path parameter.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing portal_session
Logout a portal session ¶
Logs out the portal session. Typically this should be called when customers logout of your application.
If this API is called for a Portal Session that currently is in :
- "created" status, the session status will be marked as "logged_out" and the access URL will become invalid.
- "logged_in" status, the session status will be marked as "logged_out" and customer will not be able to use that session.
- "logged_out" status, this will return normally without changing any attribute of this resource.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing portal_session
Activate a portal session ¶
When an user is sent back to your return URL with session details, you should validate that information by calling this API. The details passed to the return_url should be sent as below:
- auth_session_id - this should be sent as part of the endpoint.
- auth_session_token - this should be sent as value for the input parameter token.
Note: This API is not applicable for in-app portal.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing portal_session