PostFinance Payment Module Documentation

Last modified by Nick Weisser on Wed, September 23, 2009 06:38
Source|Old Revisions  

This is an old revision of the document!


The Magento PostFinance Module provides an interface to the SwissPostFinance E-Payment Gateway. It enables you to process various types of payments such as PostFinance Card, PostFinance E-Finance as well as all major credit cards through one single payment provider. The first two types mentioned are free of monthly and setup fees (you only need a business Post bank account with PostFinance), whereas credit card processing requires contracts with the credit card schemes in Switzerland and an up front set up fee as well as monthly fees.

The first 2 types are highly recommended for all Swiss online merchants!

Magento Connect Extension URL:

Test or Production

This module has two execution modes : Test or Production. The test url and the production url of Postfinance are defined in the postfinance/etc/mage_postfinance.xml.

How it works ?

With the configuration payment you could setup different options like colors, templates, more technical features.

So, when your customer is ready to pay he chooses between the deferent payment modules you have activated in Magento. If the Magento Postfinance Module is active and customers choose this one to pay their order a list of all allowed cards and operators appear. Customers click on what they want and confirm to pay. So it will be redirected to the Postfinance Payment page that you can customize. After a valid or and invalid transaction customers could come back to your site. In your Postfinance settings back office you can select to send a confirmation of the transaction to the customer. For that the Magento Postfinance Module transmit the customers email address to Postfinance platform. To secure the exchange the module crypt a string that certify data sent and received. A specific field configuration is mandatory (Key encrypted exchanges). If the transaction is validated orders will be in a spending state (for the moment). You have to change the state in the Magento Admin.


Title Option Definition Option
Test mode Defines if the module is in test mode or not.
Enabled Defines if you active the module or not
Title Indicates the module title. Is the designation which the customer will see.
Postfinance Identifier Is your Postfinance Identifier (PSPID)
Key encrypted exchanges Is the SHA signature which is used to crypt the … You have to active this option in the Postfinance back office. - -
Currency Select the currency allowed. For now only one selected currency.
Language The language in which the Postfinance Page will be presented to customers.
Postfinance Payment Title Page Title of you Postfinance Payment page
Page Background Color Background color for static template
Text Color Text color for static template
Table Background Color Table background color for static template
Table Text Color Table text color for static template
Button Background Color Button background color for static template
Button Text Color Button text color for static template
Font Type Font Type for static template: default = Verdana
Logo Logo filename for static template. You have to send your logo to Postfinance support with your PSPID in the subject.
Template Url page The full URL of the Template Page hosted on a secure site with a validated (not expired) “certificat” and containing the “payment string” eg: or templateSTD3.htm
Payment Success Url redirection page The url if the transaction succeeds. By default it must be : {Magento Base Url}/postfinance/postfinance/success/
Payment Failure Url redirection page The url if the transaction fails. By default it must be : {Magento Base Url}/postfinance/postfinance/error
Error Url redirection page The url if the transaction is canceled. By default it must be : {Magento Base Url}/postfinance/postfinance/error
Canceled Payment Url redirection page The url if the transaction is canceled. By default it must be : {Magento Base Url}/postfinance/postfinance/decline/
Home Site Url The url of your site
Catalog Url The url of you catalog : {Magento Base Url}/
Payment Methods Select which payment methods (Brand and Operator) that you want. You must select the same you activated on the Postfinance back office.
New order status The status after a payment succeds.

Source Code Hints

{MAGENTO_INSTALLATION}/app/etc/modules/Mage_Postfinance.xml : declares the Magento Postfinance module

{MAGENTO_INSTALLATION}/app/code/local/Mage/Postfinance : this directory is the core of this module. Inside you have the {MAGENTO_INSTALLATION}/app/code/local/Mage/Postfinance/Model/Method/Postfinance.php describes the principal Magento Postfinance module class. If you want to change de behavior of this modul see the controler class : {MAGENTO_INSTALLATION}/app/code/local/Mage/Postfinance/controllers/PostfinanceController.php


To modify the look of the block see in this directory: {MAGENTO_INSTALLATION}/app/design/frontend/default/default/template/Postfinance/


The module is currently translated to German, French and English. As this module is focusing in the Swiss market we only need an Italian (and a Rethoromanian?) translation to make it complete.

The current translation files can be found here:





I usually use the de_DE package for my Swiss clients, because the de_CH one is not maintained.


You also have some code for the admin part here: {MAGENTO_INSTALLATION}/app/design/adminhtml/default/default/template/Postfinance/

Error Messages

If you get the message no html response! when redirected back from PostFinance to your online store, got to the Transaction feedback tab in PostFinance admin panel ( and check I want to receive transaction feedback parameters on the redirection URLs.

If you get the message feedback signature is not valid! when redirected back from PostFinance to your online store, make sure that you use the same SHA signature for IN and OUT (in PostFinance admin panel), as well as for SHA1PASS and SHASign (in Magento module configuration).

If you get the message unknown order/1/r/ when being redirected to PostFinance either your SHA signature is not being calculated correctly (see PostFinance manual) or the URL of the merchant page containing the payment form that will call the page (see Data and origin verification tab in PostFinance admin panel). The URL would be {Magento Base Url}/postfinance/postfinance/redirect/ where you have to replace the content within the curly brackets with your real URL