The goal of this document is to provide installation and configuration instructions for the CCBill osCommerce billing module. This document assumes that the reader has a working knowledge of osCommerce and has already installed the osCommerce software.
The installation involves the following steps:
The CCBill osCommerce module is installed by uploading the plugin code downloaded from the CCBill website into the corresponding folders in your osCommerce installation. There are five (5) files that need to be copied:
Before installation, if you have the old version of the CCBill payment gateway, remove it from the osCommerce admin, then upload the new code.
1. In the left menu of your osCommerce admin interface, select Modules > Payment.
2. Click Install Module.
3. Select CCBill Payments from the list and click Install Module.
Once the module has been installed successfully, you will be redirected to Modules of the Payment section of the admin interface, with the new CCBill module selected.
Before using the plugin, it’s necessary to configure a few things in your CCBill account. The following CCBill settings must be correct for the payment module to work correctly.
Please work with your CCBill Support representative to activate Dynamic Pricing for your account. You can verify that Dynamic Pricing is active at Account Info > Manage the Sub Accounts > Feature Summary in the Admin Portal. Your Dynamic Pricing status appears at the bottom of the Billing Tools section.
A "salt" is a string of random data used to make your encryption more secure. You must contact CCBill Merchant Support to generate your Salt/Encryption key. Once set, it will be visible under the Advanced section of the Sub Account Admin menu. It will appear in the Encryption Key field of the Upgrade Security Setup Information section.
Since this account will be used for Dynamic Pricing transactions (not managing user subscriptions), User Management must be disabled.
1. Sign in to the Admin Portal.
2. On the Account Info mega menu, click Sub Account Admin.
3. Open the User Management menu.
4. Click Turn off User Management in the top section.
5. Select Do Not Collect Usernames and Passwords in the Username Settings section.
Payment forms are displayed to customers after they choose to check out. The payment form accepts customer payment information, processes the payment, and returns the customer to your osCommerce store where a confirmation message is displayed.
CCBill provides two types of billing forms. FlexForms is our newest (and recommended) system, but standard forms are still supported. Please choose a form type and proceed according to the section for Option 1 or Option 2, according to your selection.
To create a FlexForm form for use with osCommerce:
1. Ensure All is selected in the top Client Account drop-down menu. FlexForms are not specific to sub accounts, and cannot be managed when a sub account is selected.
2. Navigate to the FlexForms Systems tab in the top menu bar and select FlexForms Payment Links. All existing forms will be displayed in a table.
1. Click the URLs Library button in the upper-right to create a new URL. The Saved URLs Editor dialog displays.
2. Use the fields under Add New to create a new URL with the following properties.
/ext/modules/payment/ccbill/ccbill_post_handler.php?Action=Approval_Post
For example, if your osCommerce store is located at http://www.test.com, the Approval URL would be:
http://www.test.com/ext/modules/payment/ccbill/ccbill_post_handler.php?Action=Approval_Post
3. Click Save to commit your changes. Your new URL displays under Existing List.
4. Click the plus (+) symbol under Name/Value Pairs in the SANDBOX column.
5. Under Your Parameter (key), enter: zc_orderid
6. Under Use this method, select: Merchant Pass-through Parameter
7. In the third column, enter: zc_orderid
8. Under Action, click the Add button to save this parameter. Your saved parameters display under Currently Defined Name/Value Pairs.
9. Close the Name/Value Parameters editor to return to the Saved URLs Editor. Your new URL displays in the Existing List.
10. Click Promote under the Actions column. Your URL is now live.
11. Close the Saved URLs editor to return to the main FlexForms menu.
1. Click the Add New button in the upper left to create a new form.
2. The New Form dialog is displayed:
3. Promote to Live. Click the Promote to Live button to enable your new form to accept payments.
4. Note the Flex ID. Make note of the Flex ID; this value will be entered into the form name when completing the configuration in DatingPro.
Your CCBill FlexForms configuration is now complete. Please skip directly to the section titled Background Post for osCommerce.
To create a billing form for use with osCommerce:
1. Sign into the Admin Portal, and navigate to the Form Admin. All existing forms will be displayed in a table.
2. Click Create New Form in the left menu to create your new form.
3. Select the appropriate option under Billing Type. (In most cases, this will be Credit Card.)
4. Select Standard under Form Type, unless you intend to customize your form.
5. Choose a layout and click Submit at the bottom of the page.
Your new form has been created and is visible in the table under View All Forms. In this example, our new form is named 201cc.
1. Click the title of the newly-created form to edit it.
2. Select Basic from the left menu.
3. Set the following options:
FIELD NAME | VALUE |
---|---|
Site Name | Enter the URL of your osCommerce store. |
Approval URL | http://www.youroscommercestore.com/ext/modules/payment/ccbill/ccbill_process_success.php |
Denial URL | http://www.youroscommercestore.com/checkout_payment.php |
Redirect Time | Select an approval redirect time of 3 seconds, and a denial redirect time of None. |
While still in the Sub Account Admin section, select Advanced from the left menu. Notice the top section titled Background Post Information.
We will be modifying the Approval Post URL and Denial Post URL fields.
Approval Post URL | http://www.youroscommercestore.com/ext/modules/payment/ccbill/ccbill_post_handler.php?Action=Approval_Post |
Denial Post URL | http://www.youroscommercestore.com/ext/modules/payment/ccbill/ccbill_post_handler.php?Action=Denial_Post |
Your CCBill account is now configured. In your CCBill Admin interface, navigate to Sub Account Admin and ensure the information displayed is correct.
In the left menu of your osCommerce admin interface, navigate to Modules > Payment, and then select CCBill Payments. The options display on the right and clicking Edit makes the options editable.
Enter your CCBill account information. See individual field details below.
FIELD NAME | VALUE |
---|---|
Enable CCBill | Check the top box to enable payments with CCBill standard. |
Client Account Number | Enter your CCBill client account number. |
Client SubAccount Number | Enter your CCBill client sub-account number. |
Form Name | Enter the name of the form created during CCBill account configuration, or FlexForm ID if using FlexForms. |
Is Flex Form | Select Yes if using FlexForms. |
Currency | Select the billing currency. Ensure this selection matches the selection made in the Localization -> Currencies section of the osCommerce administration menu. |
Salt | Enter your salt/encryption key obtained during CCBill configuration. |
Order Status | Select the status that will be given to orders once payment has been completed. |
Under Transaction Currency, enter the three (3)-digit currency code value for the currency you want displayed to your buyers. CCBill currently supports the following currencies:
CURRENCY | CODE |
---|---|
US Dollar (USD) | 840 |
Euro (EUR) | 978 |
Australian Dollar (AUD) | 036 |
Canadian Dollar (CAD) | 124 |
Great Britain Pounds Sterling (GBP) | 826 |
Japanese Yen (JPY) | 392 |
Click Save at the bottom of the CCBill configuration section. You are now ready to process payments via CCBill!
Please conduct a few test transactions (using test data provided by CCBill) to ensure proper operation before enabling live billing mode in your CCBill account.