Home‎ > ‎Developer's Guide‎ > ‎

Hosted Self-Service Pages

The Hosted Self-Service Pages allow you to embed the "My Account" functionality from BluBilling into your own website. This allows your customer to perform self-service activities such as view their account balances and status, current and past invoices, make payments, etc. All of these self-service screens are already built into BluBilling, and may be quickly deployed within a framed page on your own website so that you maintain brand presence with your customer by keeping her on your own website.

There are two approaches for deploying the BluSynergy Self-Service Portal inside your website:
  • Single Sign On (SSO) Option - In this model, your customers have already logged on to your application/website using a set of credentials that is managed outside BluSynergy. Your application/website handles the authentication of the customer, and makes an API call to indicate the particular customer for whom the self-service portal is to be shown.
  • BluSynergy Login Option - in this model your customers login using their BluSynergy userid and password. This greatly simplifies the integration, and no API calls are required. Simply create a iframe on your webpage and set the iframe source to https://yourcompany.blubilling.com/widget/login. 
The remainder of this document refers to the SSO option.

Customer Self-service website inside your website

Step 1 - Initiate the Self-Service Page Request

In order to initiate the request, the following HTTP GET request must be initiated:

GET /rest/widget/start?params...
GET /rest/widget/start?format=xml&params...

The following query string parameters may be passed in the URL to control behavior. Note that you must first make a choice between either
  • Providing your own navigation structure (outside the framed content) for pages within the framed content OR
  • Using the default navigation elements provided  inside the framed content.

Query String Parameters

 No  Param  Description Required 
 1  cssURL  The CSS to use for styling the framed page. This permits the look and feel of the hosted payment page (i.e., the content within the iframe to match the look and feel of the framing website. To use the default BluBilling CSS, specify "/css/signup.css"
 2  customerId  The BluSynergy assigned (internal) customer id. 
 Either this OR extCustomerRef is required
 3 extCustomerRef The external customer reference ID (the customer ID used by your application) for cross-referencing. Either this OR customerId is required
 4  showNavigationBar  true or false. If true, then the BluBilling application (i.e., framed pages) will show the navigation menus for "Statements", "Payments" and "Add a Payment Method" (see the screens below). If false, then your application (i.e., outer frame) will be responsible for displaying the navigation structure that allows the user to navigate between Invoices/Payments/etc.
 No (defaults to true)
 5  loginUrl  The URL to redirect if session is expired.  Yes
 6  showStatements  true or false. If false, then the user will not be able to view their statements/invoices
 No (defaults to true)
 7 showPayments true or false. If false, then the user will not be able to view their previous payments
 No (defaults to true)
 8 allowPayments true or false. If false, then the user will not be able to make a payment towards any outstanding invoices. No (defaults to true)
 9 allowProfileEdit  true or false. If false, then the user will not be able to change their contact information No (defaults to false)
 10 editOrderOptions  Can be one or more of these values separated by a comma: Cancel,Upgrade,Downgrade,New. E.g., to permit the user full control "editOrderOptions=Cancel,Upgrade,Downgrade,New" No (defaults to none) 
 11 pdfMode   true or false. If true, then the links on the History and Statement pages will show the invoice and payment receipt in PDF mode only (as opposed to being able to view a HTML webpage that has a separate "Download PDF" link)
  No (defaults to false)
 12 profile Profile ID of self service configuration. E.g., "profile=SALESFORCE".
The profile values can be overwrite with the above parameters. Eg: if 'showStatements' is disabled (false) in SALESFORCE profile, it can be shown by passing showStatements parameter along with profile "profile=SALESFORCE&showStatements=true" 
 No (defaults to DEFAULT)
Profile Parameter

The response is dependent on whether xml format was requested or not. 

Sample request (non-XML): Note that you must supply the username and password (using basic authentication over HTTPS) in the request. The user must have the ROLE_API security role.

GET https://acme.BluBilling-test.com/rest/widget/start?cssURL=/css/widget.css&customerId=101&loginUrl=https://myapp.com/mylogin

(actual request after escaping will be of this form:)
GET https://acme.BluBilling-test.com/rest/widget/start?cssURL=%2Fcss%2Fwidget.css&customerId=101...

we get a response similar to this (with content type "text/text"):


Note: The link is valid for 30 minutes after which it expires.

Step 2 - Host a Page with an IFrame

Having got the response the hosting website can then create a web page with an iframe. The source for the iframe must be set to the url returned from Step 1 above.


    Conent for hosting website such as banner, menu, headers, etc goes here....
    <iframe frameborder="0" height="800" width="700" src="http://acme.BluBilling.com/widget/customerHome/f76b5c8e68ae4c2da69bed68845f1bc6"/>
    Footer and other content from hosting website goes here...

This causes the browser to display the webpage with the iframe content. The picture below shows the sample login.

If you set showNavigationBar=true in the request then BluBilling will display the navigation bar

On the other hand, if you are set showNavigationBar=false and showStatements =true&showPayments=true in the querystring, then BluBilling won't show the navigation bar and you can control the "My Statements" and "My Payment" menus from outside the iFrame.

Some additional screen shots of the pages within the iframe are shown below.

Invoice Details:

Pay Now:



Add a Payment Method: