Making your customers pay
A very basic payment set up with webforms and Ogone
There are a number of use cases in which you want to supply visitors of your website with a simple means of paying, but where full-blown webshop implementations like Drupal Commerce or Ubercart would be overkill because you do not really need products and order management.
Luckily, there is a light-weight solution for this by using the Webform paymethod select-module in combination with the Payment-module and one or more modules which supply payment providers. In this blog we will be using the Ogone-module.
By the way: Ogone changed its name to Ingenico and therefore exactly speaking we should be using the Ingenico-module. This module however is exactly the same as the Ogone-module, only a search-replace was appiled which changes 'ogone' to 'ingenico' in all module code, and (wrongly) even in the documentation links supplied.
Because the patch we have to apply later on was written for the Ogone-module we will use that module and not the Ingenico. And everywhere where I've written "Ogone" you should apply a search-replace to "Ogone/Ingenico" in your head.
Contrib modules
Setting up webforms to include simple payments requires a number of contrib modules to be enabled:
drush en -y webform_paymethod_select drush en -y ogone
NB: Use "drush en -y" to make sure all dependencies are installed.
You will also need to make a number of configuration steps before you can use webforms with payments.
Configure payment method
Go to
/admin/config/services/payment/method/add
To add a payment method. As explained above we are using the Ogone payment provider here, so all fields used below will be Ogone specific but other payment providers will have similar fields.
Add an Ogone payment method
Title (specific)
Basically this is the admin label.
Title (generic)
This is the label shown to customers.
Owner
This defaults to the user who creates the payment method but can be set to a other user. In combination with setting the permissions correctly this will give the selected user the ability to fully control the payment method.
PSP ID
This is the ID provided by the payment provider to you. You also use it to log in to your Ogone pages on the Ogone backoffice login so I assume it will be known to you. If not: you will absolutely need this to get the payments working.
Passphrase hashing algorithm
You have a number of choises here:
- SHA-1
- SHA-256
- SHA-512
But the important thing to remember is that whatever you choose here must also set on the Ogone page Configuration | Technical information | General security settings. Failing to do so will give errors because the encryption/decryption of sent information will fail.
Incoming passphrase and Outgoing passphrase
These password form the heart of your security settings and must always be kept a secret. Furthermore: if you are an external developer who is configuring the payments for a client it will be best practice to make the client change these passwords and the password for the Ogone backoffice after the testing period.
In this way you will not have acces to the payments made, and this is something the client really wants (not that they are not trusting you of course...).
But seriously, you do not want that this kind of information to fall into the wrong hands when, for example, your development machine is hacked (Never!!) or stolen and in the latter case the hacker in one way or another succeeds in decrypting you hard drive (you do use an encrypted hard drive, don't you?).
The passphrase you give for Incoming passphrase must also be set on the Ogone page Configuration | Technical information | Data and origin verification. If there is a mismatch between these you will get an unknown order/1/s/-error in the Configuration | Error logs.
The passphrase for Outgoing passphrase must be set on the Ogone page Configuration | Technical information | Transaction feedback. And while you are there: do not forget to set the checkbox for I would like to receive transaction feedback parameters on the redirection URLs. If you do not check this box there will be no return parameters what so ever (not even the ones Ogone says are always returned) and the Payment module will generate an access denied error when the customer returns from Ogone.
Server
When setting up payments you will always use the Ogone testing environment. Setting this wrong will give you an "unknown order/1/s/"-error in the Ogone error logs. Make sure this setting is correct and tested when the payment webforms are released to the production environment! And when all is correct force your client to change the passwords mentioned earlier.
By the way, there are a number of test-credit cards you can use on the testing environment:
- VISA: 4111111111111111
- Master Card: 5399999999999999
If you use either of these you can fill in any name, expiry date and security code you like and, great advantage, your real credit card will not be charged!
Ogone payment method brand
If you do not make any choice here the customer will be presented a list (well actually a number of icons) when she arrives at the Ogone payment page. If you Ogone subscription offers mutliple payment method (for example VISA and Mastercard) leaving this empty will be best. Or you could add multiple payment methods in Drupal, each specific for a payment mehod in Ogone, and let the customer choose before redirecting her to the Ogone payment page.
Enable the payment method
Do not forget to make sure that the checkbox "Enabled" on top of the payment method add form is checked. Ohterwise the payment method will not be avilable in the webform.
Add a webform
To enable payments on the webform you will need at least a field of the type Payment Selector. When you add this you will need (aside the default fields like 'Label', 'Form key' etc) to select the following items:
Payment Description
A short desctription.
Selected Payment Methods
Here you have to indicate which payment methods will be available for the customer. If you enable multiple payment methods the customer will have to select which method she wants to use. If you enable only one payment method this one is used automatically and no options are presented to the customer. In some themes in this case an empty fieldset will be shown. The cleanest way would be a hook_form_alter to move the content out of the fieldset, but you could also remove the border and hide te legend in CSS.
Select a currency code
The currency code is independent of selected payment method which makes it possible to use the same payment provider for multiple currencies.
Line items
Each line item represents one item the customer will be paying for. In the most basic setup you can set a fixed amount and quantity, which means every payment made through this webform will be for the same amount.
More interesting however is the possibility to select the amount and /or the quantity from an other webform element. This will make the amount payed dependent on the choices made by the customer in the rest of the webform fields. You have to make sure that the elements do have a valid number as value, so selecting a default 'Textfield' here is not a good idea. Limit yourself to either form elements of the type 'Select options' or 'Number' to make sure you have a valid number for both the amount and the quantity. Not that you don't trust your customers of course...
For each line item you have to set the tax rate and the description.
So, to review:
- You can either let the customer choose a payment method or make sure there is only one.
- Currency set here applies to all payment methods and all line items
- Tax rate and description are set per line item
Best practices
I think it is best practice to include a required e-mail field to the webform and configure the webform is such a way that the customer also receives an e-mail with the data from the webform submission.
Also alway sent an e-mail to an administrator which, besides the filled-in webform fields. also includes a link to the webform submission.It is imoprtant to so because the submission ID (eg. '76' in /node/5239/submission/76) is also used as the Merch ref in the Ogone overviews. So if you have this number you can always track the payment in Ogone, even if by some distater you have to revert your site to an earlier backup or have to reinstall the complete site.
By the way: if this should ever happen, do not forget to set the Next submission number of each payment webform hight enough to not overwrite any exsiting payments. You can do this on the edit form of the webform, under Form settings | Advanced settings.
It can happen that the functionality offered by the 'Webform Paymethod Select'-module is not enough for what you want to accomplish but Commerce would still be overkill. So one thing you could do here is use Javascript to create a form that has more possibilities (for example apply discounts according to choices made) and write the result in a read-only number field.
If you do this however, make sure you also do the same calculations serverside by adding an extra submit handler with a 'hook_form_alter' and in store the calculated amounts in the
$form_state['values']['submitted'][<element_name>]
This way you make sure that any alterations made client-side to the calculated amount are reversed. You should only use the Javascript calculations to provide the customer with feedback, and not use it as the final amount to pay. Not that you don't trust your customers of course...
Been there, done that, still not working
Ok there's a couple of things to do before you can get this working.
Ogone parameters
Ogone changed the parameters included in the feedback somewhere in 2015 and since the security SHA included in the feedbackt request is based on this parameters and access to the payment result pages is calculated by comparing the sent SHA with a calculated value, you wil get an access denied when returning from Ogone, see the function ogone_return_access() in the file ogone/ogone/ogone.module of the Ogone-module. Luckily, there is a patch for this, wich updates the parameters used in the computation.
Of course somewhere in the near future this patch (I assume) will be included in the stable verison of the Ogone module, but if you get access denied errors and you are sure the pass phrases are entered correct on both the Drupal and the Ogone side, this is a thing to check first.
Webforms says no...
After applying the forementioned patch and testing another payment, you wil get an... Access denied. But this access denied is not thrown by the payment modules but by the webform-module. The problem is caused by the fact that the payment module is not yet ported to webform 4.x, the default webfom version you get when installing the webform-module.
The solution is however reasonably simple: the 4.x branch of webform uses a token to determine if the visitor has access to the requested form submission. All we have to do is to add the token to the parameters the payment module sents to Ogone (or any other payment provider). The patch for this can be found here. If any access denied-error are thrown, make sure to check if this patch is include in the module you are using.
Ogone says no...
Sometimes there will be an error direclty when the customer lands on the Ogone payment page. There are a number of settings in Ogone to check when this happens. First of all: re-check the pass phrases are indentical and you have not swapped the ingoing and outgoing passphrases.
Also check on the Ogone page
Conclusion
So now you will have the ability to add simple payments to you webforms. Sometimes however you will notice that, with this in place, your client will be asking for more and more features and suddenly you will find yourself building a complete webshop in custom modules with extra Javascript and extra submit-handlers all over the place. When this happens, be brave enough to confront your customer and negotiate a rebuilt with either commerce (preferable) or ubercart, because very quickly this kind of augmented simple payments will prove to be totally unmaintainable. So, as a rule of thumb: Keep it simple, until keeping it simple makes things too complicated.
Documentation links