| 1 |
=== Gravity Forms eWAY === |
| 2 |
Contributors: webaware |
| 3 |
Plugin Name: Gravity Forms eWAY |
| 4 |
Plugin URI: http://snippets.webaware.com.au/wordpress-plugins/gravityforms-eway/ |
| 5 |
Author URI: http://webaware.com.au/ |
| 6 |
Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=8V9YCKATQHKEN |
| 7 |
Tags: gravityforms, gravity forms, gravity, eway, donation, donations, payment, recurring, ecommerce, credit cards, australia |
| 8 |
Requires at least: 3.6.1 |
| 9 |
Tested up to: 3.9.1 |
| 10 |
Stable tag: 1.5.12 |
| 11 |
License: GPLv2 or later |
| 12 |
License URI: http://www.gnu.org/licenses/gpl-2.0.html |
| 13 |
|
| 14 |
Add a credit card payment gateway for eWAY to the Gravity Forms plugin |
| 15 |
|
| 16 |
== Description == |
| 17 |
|
| 18 |
Gravity Forms eWAY adds a credit card payment gateway for [eWAY in Australia](http://www.eway.com.au/) to the [Gravity Forms](http://www.gravityforms.com/) plugin, using eWAY's [Direct Payments API](http://www.eway.com.au/developers/api/direct-payments.html) or [Stored Payments API](http://www.eway.com.au/developers/api/stored-%28xml%29). |
| 19 |
|
| 20 |
* build online donation forms |
| 21 |
* build online booking forms |
| 22 |
* build simple Buy Now forms |
| 23 |
* accept recurring payments |
| 24 |
|
| 25 |
> NB: this plugin extends [Gravity Forms](http://www.gravityforms.com/); you still need to install and activate Gravity Forms! |
| 26 |
|
| 27 |
= Sponsorships = |
| 28 |
|
| 29 |
* recurring payments generously sponsored by [Castle Design](http://castledesign.com.au/) |
| 30 |
|
| 31 |
Thanks for sponsoring new features on Gravity Forms eWAY! |
| 32 |
|
| 33 |
= Requirements: = |
| 34 |
* you need to install the [Gravity Forms](http://www.gravityforms.com/) plugin |
| 35 |
* you need an SSL certificate for your hosting account |
| 36 |
* you need an account with eWAY Australia |
| 37 |
* this plugin uses eWAY's [Direct Payments API](http://www.eway.com.au/developers/api/direct-payments.html) or [Stored Payments API](http://www.eway.com.au/developers/api/stored-%28xml%29), and does not support eWAY's hosted payment form |
| 38 |
|
| 39 |
= Filter hooks = |
| 40 |
|
| 41 |
Developers can use these filter hooks to modify some eWAY invoice properties. Each filter receives a string for the field value, and the Gravity Forms form array. |
| 42 |
|
| 43 |
* `gfeway_invoice_desc` for modifying the invoice description |
| 44 |
* `gfeway_invoice_ref` for modifying the invoice reference |
| 45 |
* `gfeway_invoice_trans_number` for modifying the invoice transaction reference |
| 46 |
* `gfeway_invoice_option1` for setting the option1 field (one-off payments) |
| 47 |
* `gfeway_invoice_option2` for setting the option2 field (one-off payments) |
| 48 |
* `gfeway_invoice_option3` for setting the option3 field (one-off payments) |
| 49 |
* `gfeway_invoice_cust_comments` for setting the customer comments field (recurring payments) |
| 50 |
* `gfeway_recurring_periods` for filtering the available recurring periods (from 'weekly', 'fortnightly', 'monthly', 'quarterly', 'yearly') |
| 51 |
|
| 52 |
== Installation == |
| 53 |
|
| 54 |
1. Install and activate the [Gravity Forms](http://www.gravityforms.com/) plugin |
| 55 |
2. Upload the Gravity Forms eWAY plugin to your /wp-content/plugins/ directory. |
| 56 |
3. Activate the Gravity Forms eWAY plugin through the 'Plugins' menu in WordPress. |
| 57 |
4. Edit the eWAY payment gateway settings to set your eWAY Customer ID and options |
| 58 |
|
| 59 |
Gravity Forms will now display the Credit Card and Recurring fields under Pricing Fields when you edit a form. |
| 60 |
|
| 61 |
= Building a Form with Credit Card Payments = |
| 62 |
|
| 63 |
* add one or more product fields or a total field, or a recurring field, so that there is something to be charged by credit card |
| 64 |
* add an email field and an address field if you want to see them on your eWAY transaction; the first email field and first address field on the form will be sent to eWAY |
| 65 |
* add a credit card field; if you have a multi-page form, this must be the on the last page so that all other form validations occur first |
| 66 |
* add a confirmation message to the form indicating that payment was successful; the form will not complete if payment was not successful, and will display an error message in the credit card field |
| 67 |
|
| 68 |
NB: you should always test your gateway first by using eWAY's test server. To do this, set your eWAY Customer ID to the special test ID 87654321 and select Use Test Environment. When you go to pay, the only card number that will be accepted by the test server is 4444333322221111. This allows you to make as many test payments as you like, without billing a real credit card. |
| 69 |
|
| 70 |
== Frequently Asked Questions == |
| 71 |
|
| 72 |
= What is eWAY? = |
| 73 |
|
| 74 |
eWAY is a leading provider of online payments solutions for Australia, New Zealand and the UK. This plugin integrates with the Australian Direct Payments and Stored Payments gateways, so that your website can safely accept credit card payments. |
| 75 |
|
| 76 |
= Will this plugin work without installing Gravity Forms? = |
| 77 |
|
| 78 |
No. This plugin adds an eWAY payment gateway to Gravity Forms so that you can add online payments to your forms. You must purchase and install a copy of the [Gravity Forms](http://www.gravityforms.com/) plugin too. |
| 79 |
|
| 80 |
= Can I use other eWAY gateways, outside of Australia? = |
| 81 |
|
| 82 |
Not yet. There are plans to integrate eWAY's Rapid Payments API sometime in 2013, so check back in a while. |
| 83 |
|
| 84 |
= Can I use the eWAY hosted payment form with this plugin? = |
| 85 |
|
| 86 |
No, this plugin only supports the [Direct Payments API](http://www.eway.com.au/developers/api/direct-payments.html). |
| 87 |
|
| 88 |
= What is Stored Payments? = |
| 89 |
|
| 90 |
Like Direct Payments, the purchase information is sent to eWAY for processing, but with [Stored Payments](http://www.eway.com.au/how-it-works/payment-products#stored-payments) it isn't processed right away. The merchant needs to login to their eWAY Business Centre to complete each transaction. It's useful for shops that do drop-shipping and want to delay billing. Most websites should have this option set to No. |
| 91 |
|
| 92 |
= What is Beagle? = |
| 93 |
|
| 94 |
[Beagle](http://www.eway.com.au/how-it-works/payment-products#beagle-%28free%29) is a service from eWAY that provides a level of fraud protection for your transactions. It uses information about the IP address of the purchaser to suggest whether there is a risk of fraud. You must configure [Beagle rules](http://www.eway.com.au/developers/resources/beagle-%28free%29-rules) in your MYeWAY console before enabling Beagle in this plugin. |
| 95 |
|
| 96 |
**NB**: You will also need to add an Address field to your form, and make it required. Beagle works by comparing the country of the address with the country where the purchaser is using the Internet; if you don't set it to Required, then Beagle won't be used when submitting the form without a country selected. |
| 97 |
|
| 98 |
= What Gravity Forms license do I need? = |
| 99 |
|
| 100 |
Any Gravity Forms license will do. You can use this plugin with the Personal, Business or Developer licenses. |
| 101 |
|
| 102 |
= Where do I find the eWAY transaction number? = |
| 103 |
|
| 104 |
Successful transaction details including the eWAY transaction number and bank authcode are shown in the Info box when you view the details of a form entry in the WordPress admin. Recurring payments don't get a transaction number when the payment is established, however, so only the payment status and date are recorded. |
| 105 |
|
| 106 |
= How do I add a confirmed payment amount and transaction number to my Gravity Forms notification emails? = |
| 107 |
|
| 108 |
Browse to your Gravity Form, select [Notifications](http://www.gravityhelp.com/documentation/page/Notifications) and use the Insert Merge Tag dropdown (Payment Amount, Transaction Number and Auth Code will appear under Custom at the very bottom of the dropdown list). |
| 109 |
|
| 110 |
= Why is the amount paid bigger than the form total when sandbox is enabled? = |
| 111 |
|
| 112 |
When the sandbox is enabled, the payment amount is rounded up by default, because the [eWAY sandbox server returns different error codes when the amount has cents](http://www.eway.com.au/developers/sandbox/direct-payments.html). This can be a useful feature for testing how your website displays errors, but you normally don't want it when testing a payment form. |
| 113 |
|
| 114 |
= Why do I get an error "This page is unsecured"? = |
| 115 |
|
| 116 |
When your form has a credit card field, it accepts very sensitive details from your customers and these must be encrypted. You must have an SSL certificate installed on your website, and your page must be accessed via SSL (i.e. the page address must start with "https:"). You can force a page with a credit card form to be accessed via SSL by ticking Force SSL on the Credit Card Field advanced settings page; see [screenshots](http://wordpress.org/plugins/gravityforms-eway/screenshots/). |
| 117 |
|
| 118 |
= Can I do recurring payments? = |
| 119 |
|
| 120 |
Yes, thanks to the generous sponsorship of [Castle Design](http://castledesign.com.au/). If you use [conditional logic](http://www.gravityhelp.com/documentation/page/Enable_Conditional_Logic) to hide/show a product field and a recurring payment field, you can even let customers choose between a one-off payment and a recurring payment. Payments can be scheduled for weekly, fortnightly, monthly, quarterly, or yearly billing. Examples will be presented on [the plugin's homepage](http://snippets.webaware.com.au/wordpress-plugins/gravityforms-eway/) as time permits. |
| 121 |
|
| 122 |
NB: when testing recurring payments in the Sandbox, you must use the special test customer ID 87654321. You can temporarily force this by enabling the setting "Force Test Customer ID in Sandbox". |
| 123 |
|
| 124 |
= I get an SSL error when my form attempts to connect with eWAY = |
| 125 |
|
| 126 |
This is a common problem in local testing environments. Please [read this post](http://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/) for more information. |
| 127 |
|
| 128 |
= Can I use this plugin on any shared-hosting environment? = |
| 129 |
|
| 130 |
The plugin will run in shared hosting environments, but requires PHP 5 with the following modules enabled (talk to your host). Both are typically available because they are enabled by default in PHP 5, but may be disabled on some shared hosts. |
| 131 |
|
| 132 |
* XMLWriter |
| 133 |
* SimpleXML |
| 134 |
|
| 135 |
== Screenshots == |
| 136 |
|
| 137 |
1. Options screen |
| 138 |
2. A sample donation form |
| 139 |
3. The sample donation form as it appears on a page |
| 140 |
4. How a credit card validation error appears |
| 141 |
5. A successful entry in Gravity Forms admin |
| 142 |
6. Example with recurring payments |
| 143 |
7. Forcing SSL on a page with a credit card form |
| 144 |
|
| 145 |
== Changelog == |
| 146 |
|
| 147 |
= 1.5.12 [2014-05-14] = |
| 148 |
* fixed: products with separate quantity fields fail |
| 149 |
|
| 150 |
= 1.5.11 [2014-04-01] = |
| 151 |
* fixed: load datepicker styling for Gravity Forms 1.8.6 when no other datepicker fields are present |
| 152 |
|
| 153 |
= 1.5.10 [2014-01-18] = |
| 154 |
* fixed: recurring payments failed on Windows hosting, no function strptime() |
| 155 |
* fixed: should not be able to duplicate recurring payments field in form editor |
| 156 |
* added: custom merge field for payment status |
| 157 |
|
| 158 |
= 1.5.9 [2014-01-03] = |
| 159 |
* fixed: a datepicker was being added to the bottom of the page since WordPress 3.8 (jQuery-UI bug on set datepicker options late) |
| 160 |
* fixed: clean up JSHint warnings |
| 161 |
|
| 162 |
= 1.5.8 [2013-11-10] = |
| 163 |
* fixed: settings wouldn't save in WordPress multisite installations |
| 164 |
* fixed: doco / settings page didn't explain that Beagle requires an Address field |
| 165 |
* fixed: Beagle IP address 127.0.0.1 for form submitted on server (substitutes with an Australian IP address) |
| 166 |
* changed: eWAY settings page is now a Gravity Forms settings subpage, like other addons |
| 167 |
|
| 168 |
= 1.5.7 [2013-08-23] = |
| 169 |
* fixed: a datepicker was being added to the bottom of the page when initial and start/end dates were hidden on recurring payments |
| 170 |
|
| 171 |
= 1.5.6 [2013-08-19] = |
| 172 |
* fixed: Gravity Forms 1.7.7 **changed their datepicker script handle** and broke recurring fields (not all change is good!) |
| 173 |
* fixed: can now set Show Start/End Dates without Show Initial Amount |
| 174 |
|
| 175 |
= 1.5.5 [2013-07-21] = |
| 176 |
* fixed: can select currency for Gravity Forms for forms not using credit card field, but still enforces AUD for forms with credit card field |
| 177 |
* fixed: nonce (number once) handling in settings admin |
| 178 |
* added: load unminified script if SCRIPT_DEBUG is defined / true |
| 179 |
|
| 180 |
= 1.5.4 [2013-04-21] = |
| 181 |
* fixed: recurring payments fields marked "required" were generating error "This field is required" |
| 182 |
* added: quarterly recurring time period |
| 183 |
|
| 184 |
= 1.5.3 [2013-04-07] = |
| 185 |
* fixed: don't squabble with other plugins (e.g. DPS PxPay) for custom merge tags of same name |
| 186 |
* added: recurring payments can set customer reference and invoice reference independently, through the filters `gfeway_invoice_ref` and `gfeway_invoice_trans_number` respectively |
| 187 |
|
| 188 |
= 1.5.2 [2013-03-19] = |
| 189 |
* added: filter `gfeway_invoice_trans_number` for setting the invoice transaction reference (NB: 16 character limit) |
| 190 |
|
| 191 |
= 1.5.1 [2013-02-14] = |
| 192 |
* fixed: merge tags work on new notification emails, not just on resends! |
| 193 |
* added: filter `gfeway_recurring_periods` for removing recurring payment periods, from `array('weekly', 'fortnightly', 'monthly', 'yearly')` |
| 194 |
|
| 195 |
= 1.5.0 [2013-01-26] = |
| 196 |
* added: support for [Beagle (free)](http://www.eway.com.au/developers/resources/beagle-%28free%29-rules) anti-fraud using geo-IP (Direct Payments only) |
| 197 |
* added: record authcode for transactions, and show on entry details screen |
| 198 |
* added: merge tags for authcode and beagle_score, for notification emails |
| 199 |
* changed: use WordPress function wp_remote_post() instead of directly calling curl functions |
| 200 |
|
| 201 |
= 1.4.1 [2013-01-17] = |
| 202 |
* added: when entry is stored as 'Pending' for Stored Payment, can edit and change to 'Approved' |
| 203 |
* added: record payment gateway in lead properties |
| 204 |
* changed: Stored Payments use the Direct Payments sandbox when sandbox is selected |
| 205 |
|
| 206 |
= 1.4.0 [2013-01-17] = |
| 207 |
* added: can now use eWAY Stored Payments, e.g. for merchants who do drop-shipping |
| 208 |
* added: merge tags for transaction_id and payment_amount, for notification emails |
| 209 |
|
| 210 |
= 1.3.0 [2012-10-22] = |
| 211 |
* fixed: can't submit form multiple times and get multiple payments |
| 212 |
* added: can now customise the eWAY credit card error messages |
| 213 |
|
| 214 |
= 1.2.2 [2012-10-03] = |
| 215 |
* fixed: error when recurring field is present on form, but hidden (thanks, [Simon Watson](http://moonbuggymedia.com/)!) |
| 216 |
* fixed: some undefined index PHP errors |
| 217 |
|
| 218 |
= 1.2.1 [2012-10-02] = |
| 219 |
* fixed: address on one-off eWAY invoice was getting "0, " prepended when PHP < 5.3 |
| 220 |
* fixed: address line 2 combined with line 1 when provided |
| 221 |
|
| 222 |
= 1.2.0 [2012-09-21] = |
| 223 |
* added: option to disable whether remote SSL certificate must be verified (only disable if your website can't be correctly configured!) |
| 224 |
* added: prevent XML injection attacks when loading eWAY response (security hardening) |
| 225 |
* added: recurring payments (sponsored by [Castle Design](http://castledesign.com.au/) -- thanks!) |
| 226 |
* added: if a name field is added to the form, it will be used for the eWAY customer name (NB: not cardholder name) |
| 227 |
* added: filter hooks for invoice description and reference |
| 228 |
|
| 229 |
= 1.1.0 [2012-06-17] = |
| 230 |
* added: options for extending use of eWAY sandbox (testing) environment capabilities |
| 231 |
* added: more documentation (thanks, [gymbaroo.net.au](http://gymbaroo.net.au/) and samwoods!) |
| 232 |
|
| 233 |
= 1.0.3 [2012-05-24] = |
| 234 |
* fixed: don't show settings link if Gravity Forms is not installed and activated |
| 235 |
* added: readme file makes it clear that this plugin requires Gravity Forms to be installed and activated |
| 236 |
|
| 237 |
= 1.0.2 [2012-05-13] = |
| 238 |
* fixed: correctly handle quantity for singleproduct fields |
| 239 |
* fixed: don't validate or process credit card if credit card field is hidden (e.g. other payment option selected) |
| 240 |
* fixed: form ID recorded in eWAY invoice reference field |
| 241 |
* added: cardholder's name recorded in eWAY last name field (for reference on eWAY email notification) |
| 242 |
* added: remove spaces/dashes from credit card numbers so that "valid" numbers can be passed to eWAY with spaces removed |
| 243 |
|
| 244 |
= 1.0.1 [2012-05-05] = |
| 245 |
* fixed: optional fields for address, email are no longer required for eWAY payment |
| 246 |
|
| 247 |
= 1.0.0 [2012-04-16] = |
| 248 |
* final cleanup and refactor for public release |
| 249 |
|
| 250 |
== Upgrade Notice == |
| 251 |
|
| 252 |
= 1.2.0 = |
| 253 |
* After upgrading, if you get connection errors posting to eWAY, please change your settings for "Verify remote SSL certificate"; only disable if your website can't be correctly configured! |
| 254 |
|
