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:

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

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

http://acme.BluBilling.com/signup/order/f6c0691d39b649549ad679da50a6266c

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"?>

    <signupLink>

        <url>http://acme.BluBilling.com/signup/order/f6c0691d39b649549ad679da50a6266c</url>

        <signup id="54">

            <status>DRAFT</status>

            <cssURL>/css/signup.css</cssURL>

            <successURL>http://acme.com/confirmed</successURL>

            <failURL>http://acme.com/failed</failURL>

            <tracking>f6c0691d39b649549ad679da50a6266c</tracking>

            <dateCreated>2011-07-19</dateCreated>

            ...

        </signup>

    </signupLink>


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.


<html>

    Conent for hosting website such as banner, menu, headers, etc goes here....

    <br><br>

    

    <iframe frameborder="0" height="800" width="700" src="http://acme.BluBilling.com/signup/order/f6c0691d39b649549ad679da50a6266c" />

    

    <br><br>

    Footer and other content from hosting website goes here...

</html>

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


        <!-- CUSTOMER INFORMATION -->

        <companyName>Denver Pharma and Labs</companyName>

        <firstName>John</firstName>

        <lastName>Doe</lastName>

        <extCustomerRef />

        <email>JohnDoe@denverlabs.com</email>

        <phone>555 567 5555</phone>

        <street>101 Main</street>

        <city>Denver</city>

        <state>CO</state>

        <zipcode>12345</zipcode>

        <country />

        <hideCustomerFields>false</hideCustomerFields>

        <login>JohnDoe1</login>

        <savePaymentMethod>true</savePaymentMethod>


        <!-- ORDER AND PAYMENT INFORMATION -->

        <orderNumber>1019</orderNumber>

        <contractCode>Mo-AV</contractCode>  <!-- The Plan/Contract code identifies what was purchased -->

        <quantity>5.0</quantity>                      <!-- How many items were purchased -->

        <status>PROCESSED</status>

        <startDate />                                            <!-- The Plan start date. (Future dated for free trial periods) -->

        <invoiceNumber>3421</invoiceNumber>

        <paymentAmount>84.95<paymentAmount><!-- The amount paid -->

        <paymentApprovalCode>J89WE23SBF<paymentApprovalCode>

        <billerCode />

        <couponCode />

        <sku />

        <tosAccepted>true</tosAccepted>

        <tosLink>www.acme.com/terms-of-service<tosLink />

        <hideOrderFields>false</hideOrderFields>


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

        <cardType>Visa</cardType>

        <expiry>2012-09-30</expiry>

        <cardholderName>John Doe</cardholderName>


        <!-- SYSTEM INFORMATION -->

        <tracking>f6c0691d39b649549ad679da50a6266c</tracking>

        <successURL>http://acme.com/confirmed</successURL>

        <failURL>http://acme.com/failed</failURL>

        <cssURL>/css/signup.css</cssURL>

        <dateCreated>2010-05-19</dateCreated>

</signup> 


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

The key fields to verify in the response: