EXT: heidelpay ePayment¶

What does it do?¶

The heidelpay ePayment Extension is an eCommerce payment solution that enables a web shop to receive payments through credit card (Visa, Eurocard, Mastercard, ...). It implements the heidelpay payment Platform, referring to heidelpay's current implementation guide (see URL to the Heidelpay Business Intelligence Platform). heidelpay Payment Platform 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.

NOTE: This is not a "ready-to-use" extension! Before usage, your shop system has to be slightly adapted to cooperate with the heidelpay 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 heidelpay 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 has not tested 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 site. This merchant reference will be used by acquirers and heidelpay if questions regarding a specific transaction occur. The extension uses a XML integration interface specified in the implementation guide. After entering the payment information by the customer the transaction is sent to the heidelpay Server where final payment occurs. The result transaction from heidelpay Server returns the status of the payment (successful or not successful) with further Information like return code and return messages. The extension itself returns an additional status 'aborted' 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.

The extension also supports the WPF Integration Interface because for security reason heidelpay want not allow the credit card data could be stored by the merchant.

For further Information and Documentation please please refere to Heidelpay Business Intelligence Platform with test account:

https://test.ctpe.net/bip/heidelpay_login.prc?merchant_name=demomer chant

You can login with user='testmerchant' and pwd='test'.

At this site you will find the Documentation for the different Interfaces and how to get an LIVE Account from heidelpay. Further you can check your test payment 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 heidelpay ePayment extension. This requires some PHP/TYPO3 scripting knowledge ).

Test transactions¶

The default settings for Identification and Currency code (EUR) can be used for test transactions. Use the following credit card information for testing purposes at pt_heidelpay's interface.

Session Data set for the heidelpay Extension to handle Credit Card Payment¶

There is one required array 'payment' to be stored in serialized form into the TYPO3 session in order to create an interface to the heidelpay ePayment extension:

The array has to add as prefix 'pt_heidelpay_', to ensure that this keys are not used by other extensions.

$payment = serialize($paymentArr);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_payment', $payment);

$paymentArr['type']        = 'creditCardDebit';// mandatory Type of transaction
$paymentArr['amount']      = '13.00';          // mandatory
$paymentArr['description'] = 'Testbestellung von punkt.de';   // mandatory
$paymentArr['book_id']     = 'order_test#1';   // mandatory
$paymentArr['currency']    = 'EUR';       // mandatory
$paymentArr['salt'] = '848a783b3dfc2e235a0990e67d3bb508'; // mandatory
$paymentArr['email']  = 'meine@contact.email'; // mandatory
$paymentArr['phone']  = '0721-12345';          // optional
$paymentArr['mobile'] = '0177-12345';          // optional

$paymentArr['lastname']  = 'Mustermann';       // mandatory
$paymentArr['firstname'] = 'Erika';            // mandatory
$paymentArr['company']   = 'Testfirma';        // optional

$paymentArr['street']  = 'Teststrasse 1';      // optional
$paymentArr['zip']     = '76137';              // optional
$paymentArr['city']    = 'Karlsruhe';          // optional
$paymentArr['state']   = 'DE1';                // optional
$paymentArr['country'] = 'DE';                 // mandatory

$payment = serialize($paymentArr);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_payment', $payment);

$ccard = serialize($paymentArr);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_ccinput', $ccard);

$prefix ='tx_ptheidelpay_pi1';    // Name of the Plugin
$ccArray['credit_card_holder']   = 'Dorit Rottner';       // mandatory
$ccArray['credit_card_number']   = '4111 1111 1111 1111'; // mandatory
$ccArray['credit_card_type']     = 'VISA';                // mandatory
$ccArray['valid_until_month']    = '05';             // mandatory
$ccArray['valid_until_year']     = '2007';                // mandatory
$ccArray['credit_card_verification']     = '123';  // depends on creditcard type

$ccard = serialize($ccArray);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_ccinput', $ccard);

Session Data set from heidelpay Extension for Credit Card payment¶

Finally, if a payment transaction was completed successfully or not (payment accepted, error in payment or aborted by the user), a unique transaction ID (transaction identifier) is returned by pt_heidelpay and saved with the status and return values automatically into the TYPO3 session by the extension. The session key name for this serialized array is pt_heidelpay_result.

$result = $GLOBALS['TSFE']->fe_user->getKey('ses', 'pt_heidelpay_result')
$resultArr = unserialize($result);

http://<shopdomain.com>/<returnpagename>.html>

$result = $GLOBALS['TSFE']->fe_user->getKey('ses', 'pt_heidelpay_result');
$resultArr = unserialize($result);

$status = $resultArr['status'];
$transactionId = $resultArr['transaction_id'];
$referenceId   = $resultArr['reference_id'];
$shortId       = $resultArr['short_id'];
$salt          = $resultArr['salt'];
$error_code    = $resultArr['error_code'];
$error_message = $resultArr['error_message'];

Send Credit Card payment via WPF Interface¶

To send the CreditCard Payment via WPF-Integrator, you have to use the pi3 Plugin instead of pi1 Plugin.

Your website has to be available from extern for testing, because heidelpay calls your page you have specified as response_URL after the payment transaction is done, to send the results of the WPF transaction. Don't forget to include ''http:// or 'https://' in your resonse_URL..The Response Page must be situated on a web server running on the default ports. HTTP port 80 or HTTPS port 443.

Session Data set for the heidelpay Extension to handle Credit Card Refund.¶

There is one array to be stored in serialized form into the TYPO3 session in order to create an interface to the heidelpay ePayment extension:

The array has to add as prefix 'pt:_heidelpay_', to ensure that this keys are not used by other extensions.

$payment = serialize($payment_Arr);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_payment', $payment);

$payment_Arr['type'] = 'creditCardRefund';        // Type of transaction

$payment_Arr['amount'] = '32.48';                 // maximum of the refering Debit
$payment_Arr['invoice_no'] = 'AU-200704/00701';   // order number of the refund
$payment_Arr['reference_id'] = '8a90818a12332c9d011241fc853345e0';
                                                     // Reference for the refering Debit

$payment = serialize($payment Arr);
$GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_payment', $payment);

http://<shopdomain.com>/<returnpagename>.html?refund_result=yes>

Session Data set from heidelpay Extension for Credit Card Refund¶

Finally, if a refund transaction was completed successfully or not (refund accepted, error in refund or aborted by the user), 2 unique ID's (transaction id and reference_id ) are returned by pt_heidelpay and saved with the status and return values automatically into the TYPO3 session by the extension. The session key name for this serialized array is pt_heidelpay_result. The single fields are the same as for the result of the Debit Transaction.

Extension configuration in Constant Editor¶

The Extension is widely configurable via TYPO3's “Constant Editor”, including the interfaces to your shop system and to the heidelpay payment interface. To open it, go to the TYPO3 Backend, click on "Template" in the left-frame menu, choose the page where you want include the template for heidelpay in the pagetree. First you have to include pt_heidelpay as static (from extension). Then select the "Constant Editor" from the menu in the upper right corner. There are 4 categories to configure the heidelpay extension.

Changing the extensions' CSS styles (only for plugins pi1 and pi2)¶

The default CSS styles of the extension are predefined in the file ext_typoscript_setup.txt within the property “_CSS_DEFAULT_STYLE” ; 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 heidelpay ePayment extension
plugin.tx_ptheidelpay_pi1._CSS_DEFAULT_STYLE

Configuration File pt_heidelpay_config.php (only for plugin p1 and pi2)¶

The configuration File contains three arrays which can be changed. This arrays are needed for sending via XML Interface.

Category: PT_HEIDELPAY:GENERAL¶

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

Category: PT_HEIDELPAY:XML PAYMENT¶

The following table shows the TypoScript properties of heidelpay XML Payment Configuration (Plugin pi1). Most properties are available as appropriate configuration options in TYPO3's Constant Editor.

_CSS_DEFAULT_STYLE (
    .tx-ptheidelpay-pi1-txt1 {font-size:13px; font-weight:bold; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-txt2 {font-size:11px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-txt3 {font-size:10px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-link {font-size:11px; color:#123161; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-notice {font-size:9px; font-weight:normal; color:#778899; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-tabledefault {border:1px;  margin-bottom:2px; cellspacing:4px}
    .tx-ptheidelpay-pi1-tablefixed {width:400px; border-collapse:collapse; margin-bottom:5px;}
    .tx-ptheidelpay-pi1-tableheader {border:1px; solid #edefef; padding:4px; background-color:#edefef; white-space:nowrap;}
    .tx-ptheidelpay-pi1-tablecell {border:1px padding:4px; spacing:4px}
    .tx-ptheidelpay-pi1-tablecellblind {border-left:0px; border-right:0px;}
    .tx-ptheidelpay-pi1-formdefault {margin-bottom:0px;}
    .tx-ptheidelpay-pi1-input {font-size:11px; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-select {font-size:11px; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi1-button1 {border:1px solid #edefef; background-color:#cccccc; padding:0px; font-size:11px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}

)

Category: PT_HEIDELPAY:WPF PAYMENT¶

The following table shows the TypoScript properties of of heidelpay WPF Payment Configuration (Plugin pi3). Some properties are available as appropriate configuration options in TYPO3's Constant Editor.

_CSS_DEFAULT_STYLE (
    .tx-ptheidelpay-pi3-formdefault {margin-bottom:0px;}
    .tx-ptheidelpay-pi3-button1 {border:1px solid #edefef; background-color:#cccccc; padding:0px; font-size:11px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}

)

Category: PT_HEIDELPAY:XML REFUND¶

The following table shows the TypoScript properties of heidelpay XML Refund Configuration (Plugin pi2). Some properties are available as appropriate configuration options in TYPO3's Constant Editor.

_CSS_DEFAULT_STYLE (
    .tx-ptheidelpay-pi2-txt1 {font-size:13px; font-weight:bold; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-txt2 {font-size:11px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-txt3 {font-size:10px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-link {font-size:11px; color:#123161; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-notice {font-size:9px; font-weight:normal; color:#778899; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-tabledefault {border:1px;  margin-bottom:2px; cellspacing:4px}
    .tx-ptheidelpay-pi2-tablefixed {width:400px; border-collapse:collapse; margin-bottom:5px;}
    .tx-ptheidelpay-pi2-tableheader {border:1px; solid #edefef; padding:4px; background-color:#edefef; white-space:nowrap;}
    .tx-ptheidelpay-pi2-tablecell {border:1px padding:4px; spacing:4px}
    .tx-ptheidelpay-pi2-tablecellblind {border-left:0px; border-right:0px;}
    .tx-ptheidelpay-pi2-formdefault {margin-bottom:0px;}
    .tx-ptheidelpay-pi2-input {font-size:11px; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-select {font-size:11px; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
    .tx-ptheidelpay-pi2-button1 {border:1px solid #edefef; background-color:#cccccc; padding:0px; font-size:11px; font-weight:normal; font-family:Verdana,Geneva,Arial,Helvetica,sans-serif;}
)