EXT: Cardia ePayment¶

What does it do?¶

The Cardia ePayment Extension is an eCommerce payment solution that enables a web shop to receive payments through credit card (Visa, Eurocard, Mastercard), Contopronto/LUUP SMS-payment and Telenor MobilHandel (Norway). It implements the Cardia payment solution “Cardia Shop v2.2” (see URL reference [1]), adapted referring to Cardia's current implementation guide (see URL reference [2]). Cardia Shop does not supply an e-commerce/shop application (i.e. the logic enabling the customer to order goods or services and put them into a shopping basket), but the gateway enabling merchants to receive payments.

The extension has been used in production environment for many conferences so far.

NOTE: This is not a "ready-to-use" extension! Before usage, your shop system has to be slightly adapted to co-operate with the Cardia ePayment extension - this requires some PHP/TYPO3 scripting knowledge (see chapter “Configuration”)! After this adaptation the extension has to be configured at TYPO3's Constant Editor, including the interfaces to your shop system. The Cardia ePayment extension has not been written as a dedicated add-on for the TYPO3 shop extension “tt_products”. It may also work with tt_products (after adapting it to the required needs), but I have not tested this yet .

Here's a short description of how the extension works: The extension issues a unique order identifier (hereby called the merchant reference) for each payment request. This is due to the transaction must be traceable at the merchant’s side. This merchant reference will be used by acquirers and Cardia if questions regarding a specific transaction occur. The extension uses a XML Web Service for identification and registration of required merchant details. The customer is then redirected to Cardia Server where final payment occurs (payment information is entered in a popup window from Cardia). All steps of the transaction are logged to an audit log. After finishing the payment transaction the customer is redirected to the merchants originating shop system.

URL Reference¶

This tables shows all URL references used in this document:

Screenshots¶

All screenshots are taken from Cardia ePayment v1.0.0 at production implementation for TYCon3, the 1st International TYPO3 Conference in 2005.

Fig. 1: Example of Cardia ePayment extension in production environment

Fig. 2: Cardia popup window, input form screen

Fig. 3 Cardia popup window, transaction polling screen

Fig. 4: Configuration of Cardia ePayment extension in TYPO3's Constant Editor

Integration into your shop system¶

After browsing in your shop, buying goods and supplying his personal/billing data the user finishes shopping and checks out where he choses credit card/Cardia payment as his payment alternative. At this point your shop system should redirect the user to the page where the Cardia ePayment Extension is integrated as a plugin (usually this page should have the checkbox “Hide in menu” checked at “Edit page header”). Here he's going to do the credit card payment in a popup window from Cardia.

After a successful transaction the user is being returned to your shop (see chapter “Configuration”). If problems occur or a transaction is not approved, the customer gets error messages with a link to the shop operator's contact page (configurable in Constant Editor).

Test transactions¶

The default settings for Merchant token (CF4B6B54-6C28-4FA3-86B0-E9A347D75C6C) and Currency code (NOK) can be used for test transactions. Use the following credit card information for testing purposes at Cardia's interface (popup window):

• Card number: 44443333222211111
• Expiry date: 0309
• CVC2 code (optional): 081

No cards will be charged with this configuration. Please note that transactions having an amount which ends in 1, 2, 10, 20 or 99 will NOT be approved. This is a planned limitation which helps the application developers/service integrators to test the services thoroughly. For more information about testing please refer to the Cardia implementation guide available at URL reference [2].

Running live transactions¶

To run live transactions you have to apply for your “merchant token” (a unique identifier identifying the merchant) at Cardia (contact information: see URL reference [3]). After this identifier is given to you by Cardia, you have to change the appropriate extension setting at TYPO3's Constant Editor (“Cardia--Merchant token”). Don't forget to change all other relevant “Cardia--...” settings there (e.g. “Currency code”, “Store name”, “Order description”; see chapter “Configuration”). For details about running live transactions please refer to the Cardia implementation guide available at URL reference [2] – here's the appropriate quotation:

“When a merchant is prepared to run live transactions, the merchantToken (which identifies the merchant in Cardias data backend) has to be updated. With an updated Merchant Token it is possible to run a partial live test when still standing in test mode. The amount will be reserved if authorised but not charged. When running tests in live mode all cards will be charged if authorised, and the specified amount will be deducted from the cardholders account. However, the amount can be transferred back to the cardholders’ account - a process that normally takes three bank days (for Norwegian cards).”

Debugging¶

If you encounter problems getting the extension to work, enable the debug mode (at TYPO3's Constant Editor: “Others”->”Enable debug output”) to print out details what the extension does. This is only for testing purposes, so be sure to disable the option in production environment!

Further more you may have a look at the audit log file (in the directory you've configured in Constant Editor: “Enable”->”Audit log output directory”) for debugging past transactions.

Required adaptation of your shop system¶

An adaptation of your shop system is needed to store required values into TYPO3 session keys for further processing by the Cardia ePayment extension. This requires some PHP/TYPO3 scripting knowledge (for instructions about TYPO3 session handling please refer to URL reference [5]).

There are two values to be stored into the TYPO3 session in order to create an interface to the Cardia ePayment extension:

• Amount (sum total): The first session key is mandatory and it must contain the total sum (gross amount) the customer has to pay for his shopping transaction.I:underline:MPORTANT: If decimal points are used, the decimal separator has to be a point "." and NOT a comma ","!The default name for the appropriate session key is “amountGross” - if you want to use another session key name feel free to do so, but don't forget to configure this name in Constant Editor's “Shop API-- Gross amount” property (see Reference below).
• Invoice number: The second required session key should contain the invoice number of the user's shopping transaction. This number is used for transaction logging of the extension and for the order description at Cardia.The default name for the appropriate session key is “billNo” - if you want to use another session key name feel free to do so, but don't forget to configure this name in Constant Editor's “Shop API-- Invoice No.” property (see Reference below).

Your shop system should store these values using TYPO3's session API, e.g.:

$GLOBALS["TSFE"]->fe_user->setKey('ses', 'amountGross', $yourShopsTotalSum);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'billNo', $yourShopsInvoiceNumber);

The Cardia ePayment extension reads these session keys from the TYPO3 session and uses their values for further payment processing.

Finally, if a payment transaction was completed successfully (payment accepted), a unique transaction GUID (global unique identifier) is returned by Cardia and saved automatically into the TYPO3 session by the extension. The session key name for this GUID is 'acceptedPaymentGuid'. This value is available for further processing in your shop system via PHP:

$GLOBALS['TSFE']->fe_user->getKey('ses', 'acceptedPaymentGuid')

After having saved this session key the extension returns the user to the local shop page configured in Constant Editor (“Shop API--Local return page” property) with the GUID attached to the return page URL as GET parameter 'apid' (for “accepted payment ID”), e.g.

http://<shopdomain.com>/<returnpagename>.html?apid=<accepted payment ID>

Returned to your shop, for security reasons your shop script should compare both IDs (GET param 'apid' from URL/GPvars and session key 'acceptedPaymentGuid' from TYPO3 session) to make sure everything is ok. If these IDs differ, something went wrong (or maybe there was a fraud trial) and the user should contact the shop owner (to be announced by your shop script).

Extension configuration via TypoScript/ Constant Editor¶

The Extension is widely configurable via TYPO3's “Constant Editor”, including the interfaces to your shop system and to the Cardia payment gateway. To load the default config and the config options in Constant Editor, you have to include the static extension template 'Cardia ePayment configuration' in the TypoScript template of the page where you've installed Cardia ePayment plugin.

To open TYPO3's “Constant Editor”, go to the TYPO3 Backend, click on "Template" in the left-frame menu, choose the page with the root- template in the pagetree and select the "Constant Editor" from the menu in the upper right corner. Please refer to chapter “Reference” for all available parameters.

Changing the extensions' CSS styles¶

The default CSS styles of the extension are predefined in the file ext_typoscript_setup.txt within the property “_CSS_DEFAULT_STYLE” (please refer to chapter “Reference” for default value); these styles go into the document header.

To use your own CSS styles for the extension, e.g. within an external CSS file, you have to copy the CSS classes found in the property “_CSS_DEFAULT_STYLE” to your own CSS file (you may copy the classes from the chapter “Reference”), adapt them to your needs and empty the plugin's default property “_CSS_DEFAULT_STYLE” in your root template's TypoScript setup.

// clear default CSS styles for Cardia ePayment extension
plugin.tx_ptpayment_pi1._CSS_DEFAULT_STYLE >

Reference¶

The following table shows the TypoScript properties of plugin.tx_ptpayment_pi1. Most properties are available as appropriate configuration options in TYPO3's Constant Editor.

_CSS_DEFAULT_STYLE (

    .tx-ptpayment-pi1-txt-default {font-size:13px; font-weight:normal; font-family:Arial,Helvetica,sans-serif;}
    .tx-ptpayment-pi1-txt-default a {font-size:13px; font-weight:normal; font-family:Arial,Helvetica,sans-serif;}
    .tx-ptpayment-pi1-txt-mini {font-size:11px; font-weight:normal; color:#666666; font-family:Arial,Helvetica,sans-serif;}
    .tx-ptpayment-pi1-fieldset-error {padding:8px; border:1px solid #ff9966;}
    .tx-ptpayment-pi1-legend-error {font-size:15px; font-weight:bold; color:red; font-family:Arial,Helvetica,sans-serif;}

    pre.tx-ptpayment-pi1-trace {font-size:11px; font-weight:normal; color:#666666; font-family:monospace;}
    pre.tx-ptpayment-pi1-auditlog {font-size:11px; font-weight:normal; color:#993300; font-family:monospace;}
    pre.tx-ptpayment-pi1-auditlog-error {font-size:11px; font-weight:normal; color:red; font-family:monospace;}

)