CCBill Module for Magento Installation and Configuration Created: October 8, 2014 Updated: November 13, 2017 2017 CCBill, LLC Plugin v2.0 November 2017 http://www.ccbill.com/
Table of Contents Introduction & Overview... 3 Introduction... 3 Overview... 3 Installation... 3 Verifying Installation... 3 Configure your CCBill Account... 3 Enable Dynamic Pricing... 3 Creating a Salt / Encryption Key... 4 Disabling User Management... 5 Webhook Setup... 5 Create a New Payment Form... 6 Option 1: Creating a New FlexForms Payment Form... 6 Create an Approval URL... 6 Create a New FlexForm... 7 Option 2: Creating a New Standard Payment Form... 9 Configuring the New Standard Billing Form... 10 Background Post for Magento... 11 Configuration - Magento... 12 General Options... 12 CCBill Options... 13 Confirmation... 14 Page 2 of 14
Introduction & Overview Introduction The goal of this document is to provide installation and configuration instructions for the CCBill Magento billing module. This document assumes that the reader has a working knowledge of Magento and has already installed the Magento software. Overview The CCBill Magento billing module enables easy integration of your CCBill account within the Magento e- commerce platform. Installation involves the following steps: Installing the CCBill payment module for Magento. Configuring your CCBill account for use with Magento. Configuring the module with your CCBill account information. Installation The CCBill Magento module is installed by uploading the extracted (unzipped) plugin code downloaded from the CCBill website into the /app/code/magento/ folder of your Magento installation. The result structure should be /app/code/magento/ccbill. Once you have successfully copied CCBill plugin content, execute the following command from the BIN folder in Magento: php magento setup:upgrade Verifying Installation You can verify your installation by checking in the top menu of your Magento admin interface by selecting System > Configuration. Select Payment Methods from the left menu. CCBill should be listed near the top of the Payment Methods page. If it does not appear, flush the Magento cache using the System > Cache Management section of the Magento admin interface, then return to the System > Configuration > Payment Methods section. Configure your CCBill Account 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. Enable Dynamic Pricing 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 > Feature Summary in the Admin Portal. Your Dynamic Pricing status appears at the bottom of the Billing Tools section. Page 3 of 14
Creating a Salt / Encryption Key A "salt" is a string of random data used to make your encryption more secure. CCBill Merchant Support will generate your Salt/Encryption Key. Once set, it will be visible at Sub Account Admin > Advanced. It will appear in the Encryption Key field of the Upgrade Security Setup Information section. Page 4 of 14
Disabling User Management 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 megamenu, click Sub Account Admin, then User Management on the left menu. 3. Select Turn off User Management in the top section. 4. Select Do Not Collect Usernames and Passwords in the Username Settings section. Webhook Setup For the plugin to work, you will need to set up CCBill Webhooks. To do so: 1. Log in to the CCBill Admin. 2. Open the Account Info mega menu and navigate to Sub Account Admin. 3. Select Webhooks from the navigation pane on the left. 4. Under Webhook URL, enter the base URL for your Magento store, followed by: /rest/default/v1/ccbillwebhook For example, if your Magento store is located at http://www.test.com, the Approval URL would be: http://www.test.com/rest/default/v1/ccbillwebhook Page 5 of 14
5. NewSaleSuccess and NewSaleFailure are REQUIRED Webhook notifications for the CCBill Magento plugin. 6. Select Satelite Locations and click Update to commit the changes you have made. Create a New Payment Form The billing form is the CCBill form that will be displayed to customers after they choose to check out using CCBill. The billing form accepts customer payment information, processes the payment, and returns the customer to your Magento store where a confirmation message is displayed. Important! CCBill provides two types of billing forms. FlexForms is our newest (and recommended) system, but standard forms are still supported. Please select a form type and proceed following the instructions for Option 1 or Option 2, according to your selection. Option 1: Creating a New FlexForms Payment Form Note: Skip this section if using standard forms. To set up FlexForms for use with Magento: 1. Ensure All is selected in the top Client Account dropdown 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. Create an Approval URL 1. Click the URLs Library button in the upper-right corner of the screen 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. a) URL Name. Enter a meaningful name for this URL (e.g. Payment Success). b) URL. Under URL, enter the base URL for your Magento store, followed by: Page 6 of 14
/index.php/ccbillpayment/router/index/?action=denial_post For example, if your Magento store is located at http://www.test.com, the Approval URL would be: http://www.test.com/index.php/ccbillpayment/router/index/?action=denial_post 3. Click Save to commit your changes. Your new URL displays under Existing List. 4. Promote to Live. a) Click Promote under the Actions column. Your URL is now live. b) Close the Saved URLs editor to return to the main FlexForms menu. Create a New FlexForm 1. Click the Add New button in the upper-left to create a new form. 2. The New Form dialog is displayed: a) Payment Flow Name. At the top, enter a name for the new payment flow (this will be different than the form name, as a single form can be used in multiple flows). b) Form Name. Under Form Name, enter a name for the form. c) Dynamic Pricing. Under Pricing, check the box to enable dynamic pricing. Page 7 of 14
d) Layout. Select your desired layout, and save the form. e) Edit the Flow. Click the arrow button to the left of your new flow to view the details. Under the green Approve arrow, click the square to modify the action. Page 8 of 14
f) Approval URL. In the left menu, select A URL. Select Select a Saved URL and select the URL you created earlier (e.g. Payment Success). g) Redirect Time. Select a redirect time of 1 second using the slider at the bottom and save the form. 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 Magento. Continue to the Background Post for Magento section of this document. Option 2: Creating a New Standard Payment Form Note: Skip this section if using FlexForms. 1. Sign into the Admin Portal, and navigate to the Form Admin. Page 9 of 14
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. Select the desired 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. Be sure to note the name of your new form, as it will be required in the Magento configuration section. Configuring the New Standard Billing Form Note: Skip this section if using FlexForms. 1. Click the title of the newly-created form to edit it. Page 10 of 14
2. Select Basic from the left menu. 3. Set the following options: Site Name Approval URL Denial URL Redirect Time Enter the URL of your Magento store www.yourmagentostore.com/ccbillpayment/router/index/?action=checkoutsuccess http://www.yourmagentostore.com/ccbillpayment/router/index/?action=checkoutfailure Select an approval redirect time of 3 seconds, and a denial redirect time of Instant. Background Post for Magento 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. Page 11 of 14
Approval Post URL Denial Post URL http://www.yourmagentostore.com/ccbillpayment/router/index/?action=approval_post http://www.yourmagentostore.com/ccbillpayment/router/index/?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. Configuration - Magento General Options In the top menu of your Magento admin interface, select System and then Configuration. Select Payment Methods from the left menu. CCBill should be listed near the top of the Payment Methods page. Page 12 of 14
CCBill Options In your Magento admin interface under CCBill enter the following information: Enable CCBill Merchant Account Number Ensure Yes is selected under Enabled. Enter your CCBill merchant account number. Merchant Subaccount Number Enter your CCBill merchant sub-account number. Form Name Currency Salt Enter the name of the form created during CCBill account configuration. Select the billing currency. Ensure this aligns with the selection made in the Currency Setup section of the Magento configuration menu. Enter your salt / encryption key obtained during CCBill configuration. Under Currency Code, select the default 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 Changes at the bottom of the CCBill configuration section. Page 13 of 14
Confirmation 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. Page 14 of 14