Hosted pages are used so that BluBilling can capture the initial enrollment information (consisting of customer, order and payment information) on your behalf.

Consider our example of Acme, an Internet security company that sells subscription plans for security products such as anti-virus and spam protection. Acme wishes that any new customer interested in their paid subscriptions could sign up on Acme's website, however, they do not wish to deal with credit card or billing functions. Hosted Pages make this possible by allowing Acme to frame a web page from BluBilling within their website.

The high-level sequence of steps shows the simplicity behind the approach:

1. Initiate the Self-Signup Request - Acme.com makes a web service request to BluBilling which returns a unique URL (that contains a security token)
2. Host a framed Page - Acme.com then hosts a webpage that has a HTML IFrame with its "src" attribute set to the URL returned above. BluBilling serves the main page content (containing fields for customer and credit card information).
3. Complete the Transaction - On completion, BluBilling will redirect the user back to a URL specified by Acme.
4. Verification (optional) - If desired, Acme.com can initiate another authenticated call to BluBilling to ensure that the response was valid and not manipulated.
   

Note: In order to accomodate clients of varying technical capability, the BluBilling Hosted Payment Pages allow both the customary BluBilling REST/XML programming model as well as a more simplified HTTP FORM POST model.

Step 1 - Initiate the Self-Signup Request

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

The following query string parameters may be passed in the URL. Passing these input parameters is useful when you've already captured these fields for your own application (e.g., the customer's name and email) and don't wish to force the user to re-enter the values on the hosted payment page.

Query String Parameters

No	Param	Description	Required
1	successURL	The URL to redirect to on successful signup. A tracking reference will be appended to this URL as a querystring param	Yes
2	failURL	The URL to redirect to on failed signup. A tracking reference will be appended to this URL as a querystring param	Yes
3	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"	Yes
4	hideCustomerFields	Either "true" or "false" (default). Setting this to "true" will suppress the customer related fields (name, email, etc.) on the signup form. Obviously, all customer fields must be present if this is set to true.
5	companyName	The name of the company (for B2B customers)
6.	extCustomerRef	The external customer reference ID (the customer ID used by your application) for cross-referencing.	IF hideCustomerFields = true
7.	login	The userid for logging into BluBilling
8	passwd	The plaintext password corresponding to the login
9	firstName	The customer's first name as it will appear on invoices, etc.	IF hideCustomerFields = true
10	lastName	The customer's last name as it will appear on invoices, etc.	IF hideCustomerFields = true
11	phone	The customer's primary phone
12	email	The customer's primary email. All invoices, confirmations, etc, from BluBilling will be sent to this email	IF hideCustomerFields = true
13	street	This address field will show up on invoices and may also be used for AVS (if your payment processor supports Address Validation Services)
14	city	This address field will show up on invoices and may also be used for AVS (if your payment processor supports Address Validation Services)
15	state	This address field will show up on invoices and may also be used for AVS (if your payment processor supports Address Validation Services)
16	zipcode	This address field will show up on invoices and may also be used for AVS (if your payment processor supports Address Validation Services)
17	country
18	hideOrderFields	Either "true" or "false" (default). Setting this to "true" will suppress the Order related fields (contractCode, quantity, etc.) on the signup form. Obviously, all required Order fields must be present if this is set to true
19	contractCode	The Plan Code that identifies the plan/contract that the user is subscribing to. The valid values for this field can be found under the "Product and Plans". As an example, iIf you have separate "Buy this" link for each Plan on your website, then you can associate a different contractCode for each of the links.	IF hideOrderFields = true
20	quantity	The quantity (defaults to 1)	IF hideOrderFields = true
21	startDate	The start date for the Order defaults to the current day. This may be set to a future date if you wish to offer a free trial period for example
22	sku	If a Product SKU is not provided, then all Plans for your organization are shown to the end-user for selection, This filed permits you to only show the Plans under a particular Product by providing the Product's SKU (or code)
23	couponCode	A discount coupon code
24	billerCode	The Biller reference number if this Order is to be asociated to a particular Biller. Typically used for salespeople or affiliate comissions tracking, etc.
25	tosLink	A link to a "terms of service" document on the Internet. The user will be asked to agree to these terms before placing the order.
26	displayAmount	Use one of the following keywords to control which charges are displayed on the payment page: none, allCharges, oneTimeChargesOnly, oneTimeChargesOnly
27	profileId	This corresponds to one of the profiles IDs (not profile name) under the [System >> Notifications >> Self-Service Settings] menu. The profile specifies other enrollment parameters (e.g. what payment methods are accepted, etc.)  If you have multiple sites with different profiles, then the settings may be different for each of them and the profileID allows you to pick a specific one.

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.


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


On the other hand, if we append "&format=xml" to the above request, then we get this response (with content type "text/xml"):


The "signupLink/url" element holds the url that must be used in the subsequent iframe.

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.


This causes the browser to display the webpage with the iframe content. The picture below shows the iframe content with the default CSS.

Step 3 - Complete the Transaction

Once the end user completes the transaction, either the successURL or failURL links that were provided in step 1 will be invoked. This permits the hosting website to perform any required actions on their site (such as provisioning the user, granting access, etc.)

For security reasons you should confirm that the redirect is actually sent from BluBilling and not spoofed my a malicious user. You may do this by issuing another HTTP GET request:




The sample response is shown below



Note: The comments above are not present in real transactions.

The key fields to verify in the response:

1. status - If the status is not "PROCESSED", then this signup has not gone through
   
2. orderNumber - the presense of this value indicates that an Subscription Order was created.
3. invoiceNumber - if an invoice was generated, then an invoiceNumber will be present. Note that an invoice will only be generated for a "Plan" that has one or more pre-paid "Charges". If all the charges are post-paid, then the invoice will only be generated at the end of the billing cycle (monthly)
4. paymentAmount - if an invoice is generated, then the paymentAmount field captures the amount that was processed via the payment processor. There will be a corresponding paymentApprovalCode present for cross referencing.