PostFinance E-payment Manual for Magento Commerce
This is the installation and configuration manual regarding the PostFinance E-payment extension for Magento Commerce.
Configuration - PostFinance E-payment: Merchant administration
Login to the test admin
PostFinance E-payment offers two dashboards, for test and production. Each has their own configuration, payment methods and SHA keys. See below for the correct login URLs:
- Test admin - https://e-payment.postfinance.ch/ncol/test/backoffice/
- Production admin - https://e-payment.postfinance.ch/ncol/prod/backoffice/
Configure the Account options
Go to Configuration > Account and make sure to walk through all the pages to set up your PostFinance E-payment (test) subscription. For the purpose of this manual, let's assume you have already done so.
Activate the Payment Methods
Go to Configuration > Payment methods. Make sure to configure any payment methods you wish to use in Magento. Even in Test mode you cannot test methods that are not enabled here.
Configure the Global Transaction Parameters
Go to Configuration > Technical information. There you find the first tab called Global Transaction Parameters:
- Default operation code: you can choose Sale (instant payment capture) or Authorization (delayed payment capture).
- Processing for individual transactions: set this to Always online (Immediate).
If your PostFinance E-payment subscription supports DirectLink, then you must also set the ECI value for credit card processing:
- (DirectLink only) Default ECI value: set to 7 - Ecommerce with SSL encryption. This means that in order to use DirectLink you must enable secure https:// URLs in the frontend of Magento. Contact your hosting provider about enabling secure https://.
Configure the Global Security Parameters
Go to Configuration > Technical Settings and select the tab 'Global security parameters':
- Set the Hash algorithm to SHA-512 for maximum security. Make sure that your PHP installation supports SHA-512 algorithms. This setting must also be copied to Magento (next step).
- Set the Character encoding to UTF-8?. Magento is UTF-8 too. This setting is important to work with special characters.
Configure the Payment Page
Select the tab 'Payment page':
- I recommend to uncheck the Hide cancel button, so users can cancel their payments and return to Magento to try another payment.
- Please leave the Back button redirection empty. This URL will be provided by the Magento extension.
Configure the Data and Origin Verification
- Leave the URL of the merchant page empty! We use SHA encryption, so you do not need enter anything.
- SHA-IN pass phrase, make sure to have a strong value here. You will need to copy this value to Magento.
If your PostFinance E-payment subscription supports DirectLink, then you will find these extra options:
- IP address of the server calling the APIs: in order to use DirectLink you must enter your IP address(es) here, separated with a ; (semi-colon). For example, a localhost server would be 127.0.0.1 - make sure to enter all IP addresses you will use. This is not your personal browser IP, but your server IP that hosts Magento. Use a ping command to find out what your server IP is if you don't know.
- SHA-IN pass phrase: this is another SHA field, but specifically for DirectLink payments. Make sure to enter a strong value here. You must later copy this value to Magento,
Configure the Transaction Feedback Tab
This is quite a complex tab and many people get it wrong. See the screenshot below:
Starting from the top, there are a number of important settings to configure here.
- Leave the accepturl, declineurl, exceptionurl and cancelurl? empty. These URLs are passed on by the Magento extension, you do not need to enter any URLs here.
- Check the box before the line that reads 'I would like to receive transaction feedback parameters on the redirection URLs.'
- Uncheck the box before the line that starts with 'I would like PostFinance E-payment to display a short text to the customer'. Please leave this feature disabled, it interrupts the Magento workflow.
We move on to the section called 'Direct HTTP server-to-server request':
- Set the timing of the request to Always online
- In the box that reads 'If the payment's status is "accepted", "on hold" or "uncertain".' enter the URL to your Magento site that ends in /epayment/push/accept. Make sure to enter the correct URL, with https:// or http:// (makes a difference!) etc. For example: https://magento.morningtime.com/1.7/epayment/push/accept
- In the box that reads 'If the payment's status is "cancelled by the client" or "too many rejections by the acquirer".' enter the URL to your Magento sites that ends in /epayment/push/cancel For example: https://magento.morningtime.com/1.7/epayment/push/cancel
- Set the request method to Post.
Leave the default settings for Dynamic e-Commerce parameters. Then go to the section General:
- Uncheck the box before the line that reads 'I would like PostFinance E-payment to display a "processing" message to the customer during payment processing.' This messes up the Magento workflow. Please disable it.
- Check the box that reads 'I would like PostFinance E-payment to re-launch the "end of transaction" (post-payment request/redirection) process if required.'.
Now go further down to the section 'All transaction submission modes':
- Enter a SHA-OUT pass phrase. You must later copy this value to Magento.
- Set the timing of the request to For each offline status change
- In the box that reads 'URL on which the merchant wishes to receive a deferred HTTP request', enter the URL to your Magento store that ends with /epayment/push/offline For example: https://magento.morningtime.com/1.7/epayment/push/offline
If DirectLink is part of your PostFinance E-payment subscription then you will find one more setting. Please use the default settings for Dynamic parameters.
(optional) Configure the DirectLink API User
DirectLink is an optional feature to process Credit Cards. This feature is only available for subscriptions with the DirectLink option implemented. Contact PostFinance E-payment to enable DirectLink.
Go to Configuration > Users
Find the option to add a new user. You may be limited to 2 users (yourself and 1 API user). Create a new user and configure the API user:
- Fill out the user form and enter a USERID - this will be the DirectLink API username you must enter in Magento.
- Set Profile to Admin user without user management
- Disable Scope limited to user?
- Make sure to enable Special user for API (no admin access).
- Enable all Access rights.
After saving the API user for the first time you will receive a password. You ca also receive this password via email address supplied for the API user - make sure it is a valid email address. Make sure to remember this password! This password is the DirectLink API user password which you must enter in Magento.
Go to System > Configuration > Payment Services > Appmerce PostFinance E-payment Settings
Follow the instructions to configure Magento. The most important settings are shown below:
- The PSPID is the username you use to login to the PostFinance E-payment Merchant services pages.
- (optional) This USERID is optional and can be used to distinguish multiple stores. You must setup such a USERID via the Configuration > User pages in the PostFinance E-payment dashboard.
- SHA-IN Pass phrase: copy this value from the 'Data and origin verification' tab in the PostFinance E-payment dashboard. Copy it exactly. This password is stored using PHP Mcrytp - make sure you have Mcrypt enabled for Magento.
- SHA-OUT Pass phrase: copy this value from the 'Transaction feedback' tab in the PostFinance E-payment dashboard. Copy it exactly.
- Set Operation to Sale or the same value that you entered in PostFinance E-payment. Both values must be the same.
- Set Hash algorithm to SHA-512 or the same value that you entered in PostFinance E-payment. Both values must be the same.
- Set Signature method to Parameters followed by passphrase. Very old PostFinance E-payment accounts (pre May-2010) may have a different setting.
- For using the test dashboard, make sure to enable Test Mode to Yes.
Go to System > Configuration > Payment Methods
Here you will find a list with all PostFinance E-payment payment methods. You can enable any method you need. Below is an example:
- Enable the desired method.
- Select which order statuses to use. You can create your own statuses via System > Order Statuses in Magento. Link them to the states 'pending', 'pending_payment' or 'processing'.
Important: the status feedback from PostFinance E-payment does not work behind a firewall, localhost, maintenance mode, htpasswd, htaccess ip deny, etc. Status updates only work if the site can be contacted by PostFinance E-payment.
Configure DirectLink CreditCards
There are two CreditCard payment methods for PostFinance E-payment. A 'regular' one that redirects customers to PostFinance E-payment. There is also the DirectLink variant (depends on your PostFinance E-payment contract). Below is the configuration for DIrectlink:
- Now you must enter the DirectLink User ID which you created in the PostFinance E-payment dashboard under Configuration > User.
- Also enter the DirectLink API User Password
- Enter the DirectLink SHA-IN Pass phrase - remember, this is a different one from the 'regular' SHA-IN
- Set the payment action to Authorize and Capture for immediate payments.
That's it, now you can accept payments with PostFinance E-payment.