Definitions
- Payment gateway - The service provider that acts between buyer and seller to authorize payments and transfer money (for example, Authorize.Net or PayPal).
- eZ Publish payment gateway extension - The tool that connects eZ Publish with the payment gateway (for example, the eZ Authorize extension).
- Workflow - A collection of events initiated by a trigger. A workflow defines an ordered sequence of actions that will be executed. An event is the smallest entity of the workflow system, and carries out a specific task. The Payment Gateway workflow is described in the eZ Publish documentation.
1. Download the latest eZ Authorize package. eZ Authorize packages (tar.gz, tar.bz2 and .zip) are built from the project's repository hosted by the eZ community's subversion server pubsvn.ez.no.
2. Unpack the package into the 'extension/' folder of your eZ Publish installation. Rename the unpacked eZ Authorize folder to 'ezauthorize' if it is not already named as such.
3. On Unix-like operating systems, set file ownership and permission of the 'ezauthorize' folder and configuration files to '750'.
Activate eZ Authorize via the eZ Publish Administration Interface:
1. Click on the Setup link on the top menu. On the left menu click Extensions. In the Available extensions window, check the checkbox under the Activate column that corresponds to the 'ezauthorize' extension. Click Apply changes.
2. Alternatively, you can edit the 'site.ini' override file. Typically, this involves opening the file 'settings/override/site.ini.append.php' in your preferred text editor. Add an entry to the 'ActiveExtensions[]' array with the text string 'ezauthorize' under the [ExtensionSettings] block. The basic activation settings might look similar to the following:
[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=ezauthorize
Payment gateway merchant settings
1. Copy the configuration file 'ezauthorize.ini.append.php' (located in 'extension/ezauthorize/settings/') into the 'settings/override/' directory.
2. Log in to your Authorize.Net account to obtain the optional and required settings to configure your payment gateway merchant settings in eZ Authorize.
3. Customize the settings in the file 'ezauthorize.ini.append.php', replacing the relevant values with your merchant-specific settings. One of the non merchant-specific settings is to enable or disable test mode. For testing purposes in this tutorial, make sure this value is set to 'true'. You should set it to 'false' once you have finished setting up eZ Authorize and are ready to accept payments.
Now that the extension has been installed, set up the appropriate workflows to use eZ Authorize.
Accessing the workflow interface
Click on the Setup tab on the top menu of the Administration Interface. On the left menu, near the bottom, click Workflows. The Workflow groups window will be displayed.
Workflow groups help to organize the management of workflows.
Create a new workflow group containing your site's payment gateway workflow events.
Creating a workflow group
Click the New workflow group button. The New workflow group view will be displayed. Enter a name for the workflow group, such as 'Payment Gateways', then click the OK button.
This creates a new workflow group named 'Payment Gateways' and returns to the Workflow groups view.
Next we want to add a new workflow to the 'Payment Gateways' group. Click the workflow group link Payment Gateways.
Selecting a workflow group
The workflows associated with the workflow group 'Payment Gateways' will be displayed. Add a new workflow to the workflow group by clicking the New workflow button.
Adding a new workflow event
Name the workflow 'Authorize.Net Gateway'.
On the workflow event dropdown list, select Event / Payment Gateway. Click the Add event button.
Selecting the workflow event type
The Edit workflow view will be displayed, where you can edit the workflow name, description and type. Notice the Type multi-select list of installed payment gateways workflow events. Select Authorize.Net.
Optionally, enter some descriptive text in the Description / comments field, but it is not a required field and thus can be left empty. Click the OK button.
Alternate workflow options
You can also let customers select from multiple payment gateways. Repeat the steps from the previous three sections to add another payment gateway, but name the workflow 'All Gateways' and select All from the Type multi-select list when selecting the workflow event type.
You will now have two workflows in the Workflows window (below the Payment Gateway window).
Triggers
Now that we have payment gateway workflow events, we must specify when we want this payment gateway event to happen.
In the Setup tab, click the Triggers link in the left menu.
Payment gateway events always happen in the 'shop' module during the 'checkout' function. The connection type is 'before'.
Click the select box under the Workflow column on the row shop, checkout, before.
Using triggers
You will be presented with the workflows that are configured in your application. Select the Authorize.Net workflow if you would like your customers to be required to pay via Authorize.Net. Alternatively, if you would like to give your customers the choice of paying by any additional payment gateways (eZ PayPal or Paynet being popular examples), select the 'All Gateways' workflow instead.
For the purposes of this tutorial, the 'All Gateways' workflow is selected so that we can see how the Select payment method view would look. Click Apply Changes. We have now completed all the steps you need to install a payment gateway!
Testing the commerce checkout workflow
Access the front-end user view of your website. Add a product to the shopping cart and click the Checkout button. Fill in the relevant information in the Account information form, then click the Continue button. On the Confirm order page, review your order details, then click the Confirm button.
Choosing a payment gateway
If the trigger 'shop.checkout.before' is set to the 'All Gateways' workflow, the Select payment method view will be displayed.
For this checkout example, choose the Authorize.Net option and click Select. This will start the payment gateway workflow.
If, however, the trigger 'shop.checkout.before' is set to the 'Authorize.Net' workflow, you will automatically be presented with the Payment / credit card information form.
Payment information submission
Next, you will be presented with the Payment / credit card information form.
Complete the form and click Submit. If test mode is not enabled, the payment information will be submitted to the payment gateway service and verified.
If the transaction is approved you will be directed to the order view (receipt). Payment is thus complete!
If the transaction is declined, you can re-enter the payment information and submit again until the transaction is approved. You will not be able to continue without payment approval.
When you are ready to accept payments on your site, remember to disable test mode in the configuration file 'ezauthorize.ini.append.php' (located in 'extension/ezauthorize/settings/').
Debugging
You can enable verbose debugging by first enabling the 'eZ Publish' debug output and then enabling the 'eZ Authorize' debug output (see example settings below).
In the file 'settings/override/site.ini.append.php':
[DebugSettings]
# DebugOutput=disabled
DebugOutput=enabled
In the file 'settings/override/ezauthorize.ini.append.php':
[eZAuthorizeSettings]
# Extension Debug
# Debug=false
Debug=true
Enabling this debug output will display the transaction key, merchant login, md5 secret word, and transaction hash sent to and returned from Authorize.Net.
Conclusions
We hope this tutorial has been helpful and interesting to the eZ Publish community, providing useful information about workflows, events, triggers, extensions and payment gateways in eZ Publish.
eZ Publish makes implementing payment gateway solutions simple by providing support for multiple payment gateways and powerful tools for building advanced commerce solutions.
Resources
License information
This work is licensed under the GNU Free Documentation License (GFDL).