Home‎ > ‎Developer's Guide‎ > ‎

Hosted Payment Pages for Enrollment

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:

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

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
 2  failURL  The URL to redirect to on failed signup. A tracking reference will be appended to this URL as a querystring param
 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"
 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.

GET https://acme.BluBilling.com/rest/signup/start?failURL=http://acme.com/failed&successURL=http://acme.com/confirmed&cssURL=/css/signup.css

(actual request after escaping:)
GET https://acme.BluBilling.com/rest/signup/start?failURL=http%3A%2F%2Facme.com%2Ffailed&successURL=http%3A%2F%2Facme.com%2Fconfirmed&cssURL=%2Fcss%2Fsignup.css

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"):

<?xml version="1.0" encoding="UTF-8"?>
        <signup id="54">

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.


    Conent for hosting website such as banner, menu, headers, etc goes here....
    <iframe frameborder="0" height="800" width="700" src="http://acme.BluBilling.com/signup/order/f6c0691d39b649549ad679da50a6266c" />
    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 iframe content with the default CSS.

Note: Please be aware that if the email or phone number is already in the system, then the previously registered customer account will be used. It is very common to find that potential customers abandon the signup process midway, and then came back later to try and signup again.

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:

GET /rest/signup/verify/f6c0691d39b649549ad679da50a6266c

The sample response is shown below

<?xml version="1.0" encoding="UTF-8"?>
    <signup id="56">

        <companyName>Denver Pharma and Labs</companyName>
        <extCustomerRef />
        <phone>555 567 5555</phone>
        <street>101 Main</street>
        <country />

        <contractCode>Mo-AV</contractCode>  <!-- The Plan/Contract code identifies what was purchased -->
        <quantity>5.0</quantity>                      <!-- How many items were purchased -->
        <startDate />                                            <!-- The Plan start date. (Future dated for free trial periods) -->
        <paymentAmount>84.95<paymentAmount><!-- The amount paid -->
        <billerCode />
        <couponCode />
        <sku />
        <tosLink>www.acme.com/terms-of-service<tosLink />

        <!-- PAYMENT METHOD (note: credit card number is never returned) -->
        <cardholderName>John Doe</cardholderName>

        <!-- SYSTEM INFORMATION -->

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.