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. 1. 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

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

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

<status>DRAFT</status>

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

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

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

...

</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....

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

<companyName>Denver Pharma and Labs</companyName>

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

<city>Denver</city>

<hideCustomerFields>false</hideCustomerFields>

<login>JohnDoe1</login>

<status>PROCESSED</status>

<sku />

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

<hideOrderFields>false</hideOrderFields>

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

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

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

</signup>

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

The key fields to verify in the response:

1. 1. - status - If the status is not "PROCESSED", then this signup has not gone through
    - orderNumber - the presense of this value indicates that an Subscription Order was created.
    - 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)
    - 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.