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:
- Initiate the Self-Signup Request - Acme.com makes a web service request to BluBilling which returns a unique URL (that contains a security token)
- 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).
- Complete the Transaction - On completion, BluBilling will redirect the user back to a URL specified by Acme.
- 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¶ms...
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.
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:
- 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.