Managing Multiple Products
OverviewManaging a CCBill account with the goal of selling multiple individual products can be made simple through the integration of different CCBill products. This document will explain how integration with CCBill to sell multiple products through a single sub-account can be accomplished. For direct support regarding a multiple product setup please contact firstname.lastname@example.org.
The information contained in this document assumes that you have a software development resource available to develop software that can communicate directly with CCBill data gateways.
Establishing Product IdentificationBefore you can integrate with CCBill to sell multiple products through a single sub-account you will need to establish a means to identify the products being sold and or the consumers making the purchase. The task of product/consumer identification can be accomplished through establishing a session ID, product ID, or other means of consumer identification. This document will outline a means of product identification. For example; product A may have a product ID of 10000 while product B may have a product ID of 10001 and so on and so forth.
Establishing a unique ID for each product will assist you with identifying each product that is sold through your system. Once you have established a unique ID for each product the product ID can be passed along to the CCBill Signup Form System as long as the variable name does not conflict with the signup form input type naming conventions.
Passing Product Information to CCBillOnce you have established a means through which you can identify each product being sold through your website/system you can pass the product information along to the CCBill signup form. Such a process is called a Consumer Purchase Request. When a consumer makes a purchase request on your website you should retrieve a Product ID or similar data from your database and then pass that data along to the CCBill signup form. CCBill will capture and retain the data throughout the transaction process.
The process of passing product information on to the CCBill signup form can be accomplished by building either a Dynamic Link or Dynamic Form that loads the CCBill signup form with your product data. In either case you will need to create software that will build the link or form that loads the CCBill signup form in such a way that the product information is included with the consumer traffic to the signup form.
Dynamic Link Purchase RequestThe HTML anchor example below is the output from a piece of software that will build a Dynamic Link on the Signup Now page that will load a CCBill credit card form with product identification data. While many different variables are used in the link, it is important to note the productId name value pair. Your software should determine the value of such a name value pair prior to building the output described below.
<a href=”https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900000& clientSubacc=0000&formName=7cc&allowedTypes=135&productId=10001”>Click Here to Pay via Credit Card</a>
Dynamic Form Purchase RequestThe HTML Form Code below is an example of a dynamic form button that will load the CCBill signup form that includes a product ID value. Please note the productId hidden input type which contains a dynamic value making reference to a specific product being purchased by a consumer. The following code will load a CCBill online check form with two pricing options and the product ID for product B.
<form action=”https://bill.ccbill.com/jpost/signup.cgi” method=POST> <input type=hidden name=clientAccnum value=900000> <input type=hidden name=clientSubacc value=0000> <input type=hidden name=allowedTypes value=784,835> <input type=hidden name=formName value=7ck> <input type=hidden name=productId value=10001> <input type=submit value=’Signup via Online Check’> </form>
Signup Now Variable Descriptions
|clientAccnum||Your CCBill Merchant Account Number|
|clientSubacc||Your CCBill Sub-Account Number|
|formName||The CCBill Signup Form Name|
|allowedTypes||A list of pricing type IDs separated by commas|
|productId||A dynamic variable determined by the purchase request within your system.|
Form names and allowed types values can be found in the CCBill Admin Portal's Form Administration and Price Administration reports.
Understanding the Transaction ProcessOnce you have established a means to identify a product and pass the product data on to the signup form CCBill will capture and retain the data throughout the transaction process. While many things occur during the transaction process, it is most important to understand the two different outcomes of the process—approval and denial. In each case CCBill will attempt to push the transaction data back to your system when your account is configured properly. Transaction data sent back to your system after an approval or denial will include the product information you prepared as described earlier in this document.
CCBill Background Post SystemThe CCBill Background Post System is terminology used to categorize the Approval Post URL and Denial Post URL. Essentially the system completes a transaction data push back to your website/system after a transaction has been either approved or declined by CCBill. For more information about the CCBill Background Post System see the Background Post User Guide.
Approval Post URLThe Approval Post URL is found in the Admin Portal at Account Info> Account Admin> Advanced. The Approval Post URL defines the location of software designed to receive transaction data when the transaction process is approved completed. The Approval Post URL value must be set prior to testing your multiple product support as it is the primary gateway through which you will receive specific product and consumer information after an approved transaction. The Approval Post URL software should update your system and prepare to deliver the product purchased by the consumer.
Data sent to the Approval Post URL is initiated prior to the consumer traffic seeing the aforementioned Approval Page. The data push is separate from the consumer traffic flow and unbeknownst to consumer traffic.
The overall purpose of the software located at the Approval Post URL address is to receive transaction data, update your consumer database, and respond to the CCBill system. While we are unable to provide support for updating your consumer data we recommend that your software respond to the CCBill system by printing “1”. This will ensure that the CCBill system understands that data was sent to and received by the Approval Post URL software. Keep in mind that the CCBill Background Post System will only allow 15 seconds for a response before terminating the connection and recording an error during data transmission.
Denial Post URLThe Denial Post URL value is found at Account Info> Account Admin> Advanced in the Admin Portal. The Denial Post URL value defines the location of software designed to receive transaction data after a transaction has been declined by CCBill. The Denial Post URL value is not a requirement for the multiple product integration but may be useful if you want to gather transaction data after a transaction has been declined by CCBill.
Unlike the Approval Post URL software the Denial Post URL software does not have a clear purpose. The data transmission via the Denial Post URL data push is for your convenience.
Approval PageThe Approval Page is an HTML page displayed to the consumer after a transaction has been successfully billed. The Approval Page can be customized to contain the product ID value passed into the form as previously described. The significance of having a dynamic value on the Approval Page is such that the consumer will typically click on a link leading traffic back to your website/system. Your system can then be designed to receive approval traffic along with a specific product ID. While this method is not as effective as using the Approval Post URL it can act as either a substitute or supplement to the Approval Post URL. Data sent to the Denial Post URL is separate from consumer traffic and the data push is unbeknownst to consumer traffic.
Denial PageLike the Approval Page the Denial Page is an HTML consumer target. Consumers will see the Denial Page after a transaction has been declined by CCBill. The Denial Page can be customized to receive and display a product ID value and build a dynamic link that will pass the data on to your website/system along with the consumer traffic. It is important to not confuse the Denial Page with the Denial Post URL. The Denial Page is strictly for consumer traffic while the Denial Post URL is a separate target that only transaction data is sent to.
Transaction Process OutlineAfter preparing the Signup Now page consumer traffic will flow into the CCBill signup form. CCBill will either approve or decline the transaction and may attempt to reload the signup form several times. The illustration on the next page outlines the process and shows that your product data flows through the signup form, can end up on the Approval Page, and is sent to either the Approval Post URL or the Denial Post URL.
Receiving Transaction Data
Parsing HTTP Post VariablesOnce you have an understanding of the Transaction Process you know you will have to parse data sent back to you by CCBill after a transaction approval or decline. Parsing the transaction variables can be accomplished through any scripting language such as Perl, PHP, or ASP. Below is an example of parsing the post variables using Perl.
- Perl Example:
#!/usr/bin/perl use strict vars; use CGI; my $cgi = new CGI; my %params = $cgi->Vars();
In this example all of the input parameters from the HTTP post will be stored in the params hash.
!! START PROGRAM !! // receive post from ccbill // parse 'productCode' from post // determine which password file username:password should be added to based on 'productCode' // add username and password // add subscriptionId,username, and productCode to log of active users !! END PROGRAM !!
Updating your Consumer DatabaseBecause the Background Post system is a separate post before the Approval Page or Denial Page is displayed to consumer traffic it is recommended that you update your user database when you receive the data push. Updating your database prior to consumer traffic coming back to your website/system will ensure that you are able and ready to deliver the purchased product appropriately. Because CCBill does not provide direct support for updating your consumer data after the transaction process is completed the following diagram is only a recommendation.
While CCBill can and will send consumer traffic back to your website along with a product ID via the Approval Page or Denial Page we do not recommend using this method for product delivery. CCBill can not guarantee that your website/system will be updated appropriately for product delivery and therefore we recommend the following procedure.