.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt .. role:: underline ======================= EXT: heidelpay ePayment ======================= :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed: 2008-03-14T19:16:45 :Author: Author Name :Email: your@email.com :Info 3: :Info 4: .. _EXT-heidelpay-ePayment: EXT: heidelpay ePayment ======================= Extension Key: **pt\_heidelpay** Copyright 2006, Dorit Rottner, revised for version 0.1.3, 2008-03-07 This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.com .. _Table-of-Contents: Table of Contents ----------------- **EXT: heidelpay ePayment 1** **Introduction 1** What does it do? 1 **Administration 3** Required adaptation of your shop system 3 Test transactions 3 **handle Credit Card Payment 4** Session Data set for the heidelpay Extension to handle Credit Card Payment 4 Session Data set from heidelpay Extension for Credit Card payment 6 Send Credit Card payment via WPF Interface 7 **handle Credit Card Refund 8** Session Data set for the heidelpay Extension to handle Credit Card Refund. 8 Session Data set from heidelpay Extension for Credit Card Refund 9 **Configuration 10** Extension configuration in Constant Editor 10 Changing the extensions' CSS styles (only for plugins pi1 and pi2) 10 Configuration File pt\_heidelpay\_config.php (only for plugin p1 and pi2) 11 Category: PT\_HEIDELPAY:GENERAL 12 Category: PT\_HEIDELPAY:XML PAYMENT 13 Category: PT\_HEIDELPAY:WPF PAYMENT 14 Category: PT\_HEIDELPAY:XML REFUND 15 **Known problems 16** **Changelog 16** .. _Introduction: Introduction ------------ .. _What-does-it-do: 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. .. _Administration: Administration -------------- The heidelpay ePayment extension has to be integrated into a TYPO3 page as a plugin content element. Before usage your shop system has to be slightly adapted and the pt\_heidelpay extension has to be configured in Constant Editor (see chapter “Configuration”). General requirements to use the extension: - pt\_tools Extension (Tools library developed by punkt.de) - TYPO3-Session - Curl compiled in php (Proxies defined in Typo3 installation, will be supported). - SSL for the page which handles the CreditCard Input Form if XML Interface is used. .. _Required-adaptation-of-your-shop-system: 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: 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. .. _CreditCardDebit-Transaction: CreditCardDebit Transaction """"""""""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _VISA: VISA ~~~~ .. container:: table-row Brand VISA Cart Number 4012 8888 8888 1881 4111 1111 1111 1111 4200 0000 0000 0000 Month/Year Valid Month and Year Verification 123 .. _MasterCard: MasterCard ~~~~~~~~~~ .. container:: table-row Brand MasterCard Cart Number 5105 1051 0510 5100 Month/Year Valid Month and Year Verification 123 .. _American-Express: American Express ~~~~~~~~~~~~~~~~ .. container:: table-row Brand American Express Cart Number 3111 1111 1111 117 Month/Year Valid Month and Year Verification 1234 .. ###### END~OF~TABLE ###### No cards will be charged with this configuration. For more information about testing please refer to the heidelpay implementation guide. .. _handle-Credit-Card-Payment: handle Credit Card Payment -------------------------- .. _Session-Data-set-for-the-heidelpay-Extension-to-handle-Credit-Card-Payment: 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. .. ### BEGIN~OF~TABLE ### .. _type: type """" .. container:: table-row Property type Data type string Description The field must have the value 'creditCardDebit'. Mandatory / Optional mandatory .. _salt: salt """" .. container:: table-row Property salt Data type string (32) Description The field must contain an md5 hash which is used for verification of an successful Response'. Mandatory / Optional mandatory .. _amount: amount """""" .. container:: table-row Property amount Data type string Description The field 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 ","! Mandatory / Optional mandatory .. _description: description """"""""""" .. container:: table-row Property description Data type String (0..128) Description This field must contain description of the user's shopping transaction. It is used for the order description at heidelpay. Mandatory / Optional mandatory .. _book-id: book\_id """""""" .. container:: table-row Property book\_id Data type String Description This field must contain unique Identifier of the user's shopping transaction. It is used for transaction logging of the extension. Mandatory / Optional mandatory .. _currency: currency """""""" .. container:: table-row Property currency Data type String (3) Description The string contains the currency Code.The complete List of supported currencies and their codes is available for download on the heidelpay Server. Mandatory / Optional mandatory .. _email: email """"" .. container:: table-row Property email Data type string (6..128) Description The field contains the Email-address of the customer. Mandatory / Optional mandatory .. _phone: phone """"" .. container:: table-row Property phone Data type String (8..64) Description The field contains the phone number of the customer. Mandatory / Optional optional .. _mobile: mobile """""" .. container:: table-row Property mobile Data type String (10..64) Description The field contains the mobile phone number of the customer. Mandatory / Optional optional .. _street: street """""" .. container:: table-row Property street Data type String (5..50) Description The field contains the street and house number of the customer. If to long the field will be shortened by the extension. Mandatory / Optional optional .. _zip: zip """ .. container:: table-row Property zip Data type String (3..6) Description The field contains the zip code of the customer. Mandatory / Optional optional .. _city: city """" .. container:: table-row Property city Data type String (2..30) Description The field contains the city of the customer. If to long the field will be shortened by the extension. Mandatory / Optional optional .. _country: country """"""" .. container:: table-row Property country Data type string (2) Description The field contains the Country Code of the customer.The Country Codes are specified in ISO 3166-1. The complete List of supported countries and their codes is available for download on the heidelpay Server. Mandatory / Optional mandatory .. _state: state """"" .. container:: table-row Property state Data type string (3) Description The field contains the state code of the city of the customer.The field is not required for many countries. The complete List of supported states and their codes is available for download on the heidelpay Server. Mandatory / Optional optional .. _lastname: lastname """""""" .. container:: table-row Property lastname Data type string (2:..40) Description The field contains the last name of the customer. If to long the field will be shortened by the extension. Mandatory / Optional .mandatory .. _firstname: firstname """"""""" .. container:: table-row Property firstname Data type string (2:..40) Description The field contains the first name of the customer. If to long the field will be shortened by the extension. Mandatory / Optional mandatory .. ###### END~OF~TABLE ###### [pt\_heidelpay\_payment] Your shop system should store these values using TYPO3's session API, e.g.: :: $payment = serialize($paymentArr); $GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_payment', $payment); The heidelpay ePayment extension reads these session keys from the TYPO3 session and uses their values for further payment processing. .. _generated: ((generated)) """"""""""""" .. _Example-setting-session-data-to-the-heidelpayExtension: Example setting session data to the heidelpayExtension: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $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); An additional optional array 'cc\_input' could be stored in serialized form into the TYPO3 session to deliver already entered credit Card data. This data will only handled when sending the data via XML Interface (plugin pi1). For the WPF Interface this data will be ignored. The array has to add as prefix 'pt\_heidelpay\_', to ensure that this keys are not used by other extensions. .. ### BEGIN~OF~TABLE ### .. _credit-card-holder: credit\_card\_holder '''''''''''''''''''' .. container:: table-row Property credit\_card\_holder Data type string Description The field contains the given- and lastname of the creditcard holder. Mandatory / Optional mandatory .. _credit-card-number: credit\_card\_number '''''''''''''''''''' .. container:: table-row Property credit\_card\_number Data type string Description The field contains the creditcard number (only digits and blanks are allowed). Mandatory / Optional mandatory .. _credit-card-type: credit\_card\_type '''''''''''''''''' .. container:: table-row Property credit\_card\_type Data type string Description The field contains the creditcard type (should be from the List from pt\_heidelpay) Mandatory / Optional mandatory .. _credit-card-verification: credit\_card\_verification '''''''''''''''''''''''''' .. container:: table-row Property credit\_card\_verification Data type string Description This field contains the cvv or cvv2 number of the creditcard (only mandatory for 'MasterCard, VISA and Anerican Express') Mandatory / Optional Depends on credit card type .. _valid-until-month: valid\_until\_month ''''''''''''''''''' .. container:: table-row Property valid\_until\_month Data type integer(2) Description This field must contain the month part of valid until. Mandatory / Optional mandatory .. _valid-until-year: valid\_until\_year '''''''''''''''''' .. container:: table-row Property valid\_until\_year Data type integer (4) Description This field must contain the year part of valid until. Mandatory / Optional mandatory .. ###### END~OF~TABLE ###### [pt\_heidelpay\_ccinput] Your shop system should store these values using TYPO3's session API, e.g.: :: $ccard = serialize($paymentArr); $GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_ccinput', $ccard); .. _Example-setting-session-data-for-credit-card-input-to-the-heidelpay-Extension: Example setting session data for credit\_card\_input to the heidelpay Extension: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $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: 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. .. ### BEGIN~OF~TABLE ### .. _status: status """""" .. container:: table-row Property status Data type string Description The field indicates if payment was accepted or not. There are the following possible values: - successful – Payment was successful - notSuccessful – An error occurred during Payment - aborted – Payment aborted by user Mandatory / Optional mandatory .. _amount: amount """""" .. container:: table-row Property amount Data type string Description The field contains the total sum (gross amount) the customer has to pay for this shopping transaction. The decimal places are separated with '.'. Mandatory / Optional mandatory .. _description: description """"""""""" .. container:: table-row Property description Data type String (0..128) Description This field contains the description of the user's shopping transaction. It is used for the order description at heidelpay. Mandatory / Optional mandatory .. _book-id: book\_id """""""" .. container:: table-row Property book\_id Data type string Description This field must contain unique Identifier of the user's shopping transaction. It is used for transaction logging of the extension. Mandatory / Optional mandatory .. _currency: currency """""""" .. container:: table-row Property currency Data type string Description The string contains the currency Code. Mandatory / Optional mandatory .. _return-code: return\_code """""""""""" .. container:: table-row Property return\_code Data type string (11-12) Description Return code set from the heidelpay Server or the heidelpay extension. Mandatory / Optional mandatory .. _return-message: return\_message """"""""""""""" .. container:: table-row Property return\_message Data type string Description Return Mode set from the heidelpay Server or the heidelpay extension. Mandatory / Optional mandatory .. _transaction-id: transaction\_id """"""""""""""" .. container:: table-row Property transaction\_id Data type string (32) Description The unique transaction Identifier generated by the heidelpay extension and stored on the payment Server. Mandatory / Optional mandatory .. _short-id: short\_id """"""""" .. container:: table-row Property short\_id Data type string (14) Description ID which is used formanual entry and search purposes. The likelihood for uniqueness is very high, but not guaranteed. This field is only set from the WPF Interface (plugin pi3), because heidelpay shows the user only this ID in the WEB Frontend. Mandatory / Optional optional .. _reference-id: reference\_id """"""""""""" .. container:: table-row Property reference\_id Data type string (32) Description The unique Identifier generated by the heidelpay Server for further handling like refund transaction. This field is only set if an transaction issend to the heidelpay server. Mandatory / Optional optional .. ###### END~OF~TABLE ###### [pt\_heidelpay\_result] These values are available for further processing in your shop system via PHP: :: $result = $GLOBALS['TSFE']->fe_user->getKey('ses', 'pt_heidelpay_result') $resultArr = unserialize($result); After having saved resultArr the extension returns the user to the local shop page configured in Constant Editor (“Shop API--Local return page” property) with parameter debit\_result attached to the return page URL as GET parameter , e.g. :: http:///.html> Returned to your shop, for security reasons your shop script should check in case of success the success\_hash. This hash is build from description, amount and salt send by the Debit Request. This hash is used for verification that the result is really build by the extension. .. _generated: ((generated)) """"""""""""" .. _Example-for-retrieving-session-date-set-by-the-heidelpay-Extension: Example for retrieving session date set by the heidelpay Extension. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $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: 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. .. _handle-Credit-Card-Refund: handle Credit Card Refund ------------------------- .. _Session-Data-set-for-the-heidelpay-Extension-to-handle-Credit-Card-Refund: 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. .. ### BEGIN~OF~TABLE ### .. _type: type """" .. container:: table-row Property type Data type string Description The field must have the value 'creditCardRefund'. Mandatory / Optional mandatory .. _salt: salt """" .. container:: table-row Property salt Data type string (32) Description The field must contain an md5 hash which is used for verification of an successful Response'. Mandatory / Optional mandatory .. _amount: amount """""" .. container:: table-row Property amount Data type string Description The field 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 ","! Mandatory / Optional mandatory .. _description: description """"""""""" .. container:: table-row Property description Data type string Description This field must contain description of the user's shopping transaction. It is used for the order description at heidelpay. Mandatory / Optional mandatory .. _book-id: book\_id """""""" .. container:: table-row Property book\_id Data type string Description This field must contain unique Identifier of the user's shopping transaction. It is used for transaction logging of the extension. Mandatory / Optional mandatory .. _currency: currency """""""" .. container:: table-row Property currency Data type String (3) Description The string contains the currency Code.The complete List of supported currencies and their codes is available for download on the heidelpay Server [4]. Mandatory / Optional mandatory .. _reference-id: reference\_id """"""""""""" .. container:: table-row Property reference\_id Data type string (32) Description This field must contain the unique Reference Id send from the heidelpay Server to which Debit transaction of this Refund Request belongs . Mandatory / Optional mandatory .. ###### END~OF~TABLE ###### [pt\_heidelpay\_payment] Your shop system should store these values using TYPO3's session API, e.g.: :: $payment = serialize($payment_Arr); $GLOBALS["TSFE"]->fe_user->setKey('ses', 'pt_heidelpay_payment', $payment); The heidelpay ePayment extension reads this session key from the TYPO3 session and uses their values for further payment processing. .. _generated: ((generated)) """"""""""""" .. _Example-setting-session-data-to-the-heidelpay-Extension: Example setting session data to the heidelpay Extension: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $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); 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 with parameter refund\_result attached to the return page URL as GET parameter , e.g. :: http:///.html?refund_result=yes> Returned to your shop, for security reasons your shop script should check in case of success the success\_hash. This hash is build from description, amount and salt send by the Debit Request. This hash is used for verification that the result is really build by the extension. .. _Session-Data-set-from-heidelpay-Extension-for-Credit-Card-Refund: 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. .. _Configuration: Configuration ------------- .. _Extension-configuration-in-Constant-Editor: 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. .. _Shop-API-parameters: 'Shop API' parameters """"""""""""""""""""" Use the “Shop API--” settings in Constant Editor to create the interface to your shop system (that has been adapted for co-operating with pt\_heidelpay as described above in chapter “Required adaptation of your shop system”). You have to configure several page identifiers (TYPO3 page ID [pid] or alias) for result and error processing. .. _Heidelpay-parameters: 'Heidelpay' parameters """""""""""""""""""""" The Constant Editor settings prefixed with “Heidelpay--” are parameters used for the heidelpay payment gateway. For detailed description of special heidelpay parameters please refer to the heidelpay Technical Quickstart Documentation avilable at the Heidelpay Business Intelligence Platform. The extension's default settings for heidelpay can be used for test transactions (see chapter “Administration”). For live transactions in your production phase you have to apply for an unique merchant token at heidelpay. .. _Changing-the-extensions-CSS-styles-only-for-plugins-pi1-and-pi2: 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. .. _generated: ((generated)) """"""""""""" .. _Example: Example ~~~~~~~ :: // 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: **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. .. _ptheidelpay-cc-types: ptheidelpay\_cc\_types """""""""""""""""""""" The first array issued to specify the supported CreditCart brans. A maximum list of all CreditCard brands supported by the heidelpay Payment Server is specified in the Default configuration File. The user can delete brands he don't want to support in his environment. He also can change the values in the Array ptheidelpay\_cc\_types. But he should not change the keys, because these keys are needed from the payment server. .. _ptheidelpay-cc-cvv: ptheidelpay\_cc\_cvv """""""""""""""""""" This array is used to specify for which creditcard brand cvv verification is required. .. _ptheidelpay-rcs: ptheidelpay\_rcs """""""""""""""" This array contains the Return codes from pt\_heidelppay which are handled in the Extension itself. All other return codes are redirected to an error page and have to be handled from the application which uses the heidelpay extension. The complete list of return codes can be found under heidelpays Reurncode speciffication (see URL[3]). Additional return codes starting with '1000' are set from the extension itself, when no connection to payment server is done. .. _Category-PT-HEIDELPAY-GENERAL: 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. .. ### BEGIN~OF~TABLE ### .. _logDir: logDir """""" .. container:: table-row Property logDir Data type string Description **Audit log output directory** : Directory path for generated audit log (absolute server path, don't forget the prefacing and closing slashes "/"). Default .. _systemMail: systemMail """""""""" .. container:: table-row Property systemMail Data type string Description **Email address for system mails** : Email address for auto-generated mails of this plugin (e.g. logging errors). Default .. _Unknown-Property: ((Unknown Property)) """""""""""""""""""" .. container:: table-row Property Data type Description Default .. _errorPageCreditCardDebit: errorPageCreditCardDebit """""""""""""""""""""""" .. container:: table-row Property errorPageCreditCardDebit Data type string Description **ShopAPI--CreditCard Debit error page** : Identifier (PID or alias) of your TYPO3 shop page where the user should be redirected for further processing after error occured during the ePayment creditCard Debit transaction. Default .. _returnPageCreditCardDebit: returnPageCreditCardDebit """"""""""""""""""""""""" .. container:: table-row Property returnPageCreditCardDebit Data type string Description S **hopAPI--CreditCard Debit return page** : Identifier (PID or alias) of your TYPO3 shop page where the user should be redirected for further processing after completing the ePayment creditCard Debit transaction. Default .. _errorPageCreditCardRefund: errorPageCreditCardRefund """"""""""""""""""""""""" .. container:: table-row Property errorPageCreditCardRefund Data type string Description **ShopAPI--CreditCard Refund error page** : Identifier (PID or alias) of your TYPO3 shop page where the user should be redirected for further processing after error occured during the ePayment creditCard Refund transaction. Default .. _returnPageCreditCardRefund: returnPageCreditCardRefund """""""""""""""""""""""""" .. container:: table-row Property returnPageCreditCardRefund Data type string Description S **hopAPI--CreditCard Refund return page** : Identifier (PID or alias) of your TYPO3 shop page where the user should be redirected for further processing after completing the ePayment creditCard Refundt transaction. Default .. _merchantName: merchantName """""""""""" .. container:: table-row Property merchantName Data type string Description **ShopAPI--Merchant name** : Name of your shop Default .. _heidelpayCharset: heidelpayCharset """""""""""""""" .. container:: table-row Property heidelpayCharset Data type string Description **Heidelpay--Charset** Charset encoding used by heidelpay. Default *iso-8859-1* .. _currencyCode: currencyCode """""""""""" .. container:: table-row Property currencyCode Data type string Description **Heidelpay--List of valid Currency codes** : The ISO three letter currency codes specifying the currency to use (e.g. EUR for Euro, GBP for British pounds, NOK for Norwegian kroner, SEK for Swedish kroner, DKK for Danish kroner). The default code for testing (in combination with the test merchant token, see 'Merchant token' above) is EUR. If there is more than one CurrencyCode, they have to be separarted by ','. The currency set in the session for Refund or Debit Transaction have to be one of these. Default EUR .. _sender: sender """""" .. container:: table-row Property sender Data type string Description **Heidelpay--Sender** A unique identifier identifying the merchant. The ID is given to you by heidelpay. The default sender is a test sender for standard transaction testing. Default *d225a9fefe3fbaf400fe43281064000a* .. _channel: channel """"""" .. container:: table-row Property channel Data type string Description **Heidelpay--Channel** : A unique identifier identifying the channel of the merchant (a merchant can have multiple channels for different purposes). The ID is given to you by heidelpay. The default channel is a test channel for standard transaction testing. Default D225a9fefe3fbaf400fe43294aca000d *[\*without blanks!\*]* .. _userId: userId """""" .. container:: table-row Property userId Data type string Description **Heidelpay--UserId** : A unique identifier identifying the user of the merchant (a merchant can have several logins for system users and human users). The ID is given to you by heidelpay. The default userId is a test userId for standard transaction testing (This test userId can change. So you have to verify it by heidelpay). Default D225a9fefe3fbaf400fe43275771000 *[\*without blanks!\*]* .. _userPasswd: userPasswd """""""""" .. container:: table-row Property userPasswd Data type string Description **Heidelpay--UserPasswd** : A password which fits the login UID has to be provided. It is distributed together with the userId. The default passwd is a test passwd for standard transaction testing (This test userPasswd can change. So you have to verify it by heidelpay). Default test .. _token: token """"" .. container:: table-row Property token Data type string Description **Heidelpay--Token** :A token which fits the token has to be provided. It is distributed together with userId and userPasword. The default token is a test token for standard transaction testing (This test token can change. So you have to verify it by heidelpay). Default test .. _transactionMode: transactionMode """"""""""""""" .. container:: table-row Property transactionMode Data type string Description **Heidelpay--TransactionMode** : The Mode tage has three different attributes which determines the processing of the transaction (INTEGRATOR\_TEST, CONNECTOR\_TEST, LIVE). The default mode is CONNECTOR\_TEST for standard transaction testing. Default CONNECTOR\_TEST .. ###### END~OF~TABLE ###### [PT\_HEIDELPAY:GENERAL] .. _Category-PT-HEIDELPAY-XML-PAYMENT: 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. .. ### BEGIN~OF~TABLE ### .. _SendURL-for-plugin-pi1: SendURL for plugin pi1 """""""""""""""""""""" .. container:: table-row Property SendURL for plugin pi1 Data type string Description **Heidelpay XML--URL** : The XML Transaction will be send to this URL. The default URL is a test URL for standard transaction testing. Default test.ctpe.net/payment/ctpe *[\*without blanks!\*]* .. _abortLabel: abortLabel """""""""" .. container:: table-row Property abortLabel Data type string Description **Heidelpay--abort text** Use this label from locallang to abort Credit Card Payment (possible Value "payOnAccount" and "abort"). Default payOnAccount .. _sendWithoutShow: sendWithoutShow """"""""""""""" .. container:: table-row Property sendWithoutShow Data type boolean Description **Heidelpay--send without show** Send Request to Heidelpay without showing Input Form (Only operative if credit card input is set into session key=tx\_ptheidelpay\_pi1\_cc\_input, and input is syntactical correct). Default 1 .. _configFile: configFile """""""""" .. container:: table-row Property configFile Data type file Description **Configuration File pt\_heidelpay** : In this file Configurations like accepted Credit Card types will be set. The Default contains all accepted CreditCards from Heidelpay. If it is not set a Default configurationFile is used. (only used for plugin pi1 and pi2) Default typo3conf/ext/pt\_heidelpay/pt\_heidelpay\_config.php .. _templateFilePayment: templateFilePayment """"""""""""""""""" .. container:: table-row Property templateFilePayment Data type file Description **Payment display template** The template file to be used for the payment display of plugin pi1 (template for the Smarty templating engine). Default pt\_heidelpay/res/smarty\_tpl/payment.tpl.html .. _CSS-DEFAULT-STYLE: \_CSS\_DEFAULT\_STYLE """"""""""""""""""""" .. container:: table-row Property \_CSS\_DEFAULT\_STYLE Data type string Description **Default CSS styles** (these go into the document header) - please change styles in your template setup (TypoScript). The default setting in file ext\_typoscript\_setup.txt is: :: _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;} ) Default *(see description)* .. ###### END~OF~TABLE ###### [PT\_HEIDELPAY:XML PAYMENT] .. _Category-PT-HEIDELPAY-WPF-PAYMENT: 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. .. ### BEGIN~OF~TABLE ### .. _SendURL-for-plugin-pi3: SendURL for plugin pi3 """""""""""""""""""""" .. container:: table-row Property SendURL for plugin pi3 Data type string Description **Heidelpay WPF--URL** : The WPF Transaction will be send to this URL. The default URL is a test URL for standard transaction testing. Default test.ctpe.net/payment/payment.prc *[\*without blanks!\*]* .. _frontendWpfLight: .frontendWpfLight """"""""""""""""" .. container:: table-row Property .frontendWpfLight Data type boolean Description **Heidelpay--Frontend WPF-LIGHT** The Mode WPF-LIGHT is set if user has disabled Javascript on his browser. If set to false no payment could be done with Javascript disabled (an Error message is shown for the user). If enabled Heidelpay didn't do any checking of the users input and send the transaction directly to the CreditCard Company. This could cause additional transaction fees for the merchant. Default false .. _frontendResponseURL: frontendResponseURL """"""""""""""""""" .. container:: table-row Property frontendResponseURL Data type string Description **Heidelpay--Frontend Response URL** URL which is called from Heidelpay after payment with serverprefix ('httpd://' or 'https://'). Default .. _frontendPopup: frontendPopup """"""""""""" .. container:: table-row Property frontendPopup Data type boolean Description **Heidelpay--Frontend Popup** Indicates if Heidelpay input Side will popup in own Window or not. Default true .. _frontendHeight: frontendHeight """""""""""""" .. container:: table-row Property frontendHeight Data type integer Description **Heidelpay--Frontend Height** Height of frontend Window in Pixel. If not specified the Default Value of Heidelpay is used (600). Default 600 (set by heidelpay) .. _frontendFormWidth: frontendFormWidth """"""""""""""""" .. container:: table-row Property frontendFormWidth Data type integer Description **Heidelpay--Frontend Form Width** Width of frontend payment form in Pixel, if frontendPopup = 'false'. If not specified the width is 100% of the frame the form is embedded in. Default 100% (set by heidelpay) .. _frontendOnlyCreditCardBlock: frontendOnlyCreditCardBlock """"""""""""""""""""""""""" .. container:: table-row Property frontendOnlyCreditCardBlock Data type boolean Description **Heidelpay--Frontend onlyCreditCardBlock** Indicates that only CreditCard Block is shown on the frontend. Default 1 .. _frontendCssPath: frontendCssPath """"""""""""""" .. container:: table-row Property frontendCssPath Data type string Description **Heidelpay--Frontend Css Path** Path to own style-sheet relative to root path of web presence. Default typo3conf/ext/pt\_heidelpay/pi3/css/heidelpay.css .. _frontendShopName: frontendShopName """""""""""""""" .. container:: table-row Property frontendShopName Data type string Description **Heidelpay--Frontend Shop Name** Name of the shop that appears on the WPF Screens . Default .. _frontendSupportNumber: frontendSupportNumber """"""""""""""""""""" .. container:: table-row Property frontendSupportNumber Data type string Description **Frontend Support Number** Phone number, that an enduser can call if the payment was not successful (Default Value is configured on BIP). Default .. _frontendSupportEmail: frontendSupportEmail """""""""""""""""""" .. container:: table-row Property frontendSupportEmail Data type string Description **Heidelpay--Frontend Support Email** Email address, that an enduser can call if the payment was not successful (Default Value is configured on BIP). Default .. _frontendCloseRedirectTime: frontendCloseRedirectTime """"""""""""""""""""""""" .. container:: table-row Property frontendCloseRedirectTime Data type integer Description **Heidelpay--Frontend Closing or Redirect Time** Time in seconds to close frontend popup or redirect to the merchants site (Default Value 0). Default 0 .. _templateFileEnableJavascript: .templateFileEnableJavascript """"""""""""""""""""""""""""" .. container:: table-row Property .templateFileEnableJavascript Data type file Description **Enable Javascript display template** The template file to be used for showing the Enable Javascript Message (template for the Smarty templating engine). Default EXT:pt\_heidelpay/res/smarty\_tpl/enableJavascript.tpl.html .. _CSS-DEFAULT-STYLE: \_CSS\_DEFAULT\_STYLE """"""""""""""""""""" .. container:: table-row Property \_CSS\_DEFAULT\_STYLE Data type Description :: _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;} ) Default *(see description)* .. ###### END~OF~TABLE ###### [PT\_HEIDELPAY:WPF PAYMENT] .. _Category-PT-HEIDELPAY-XML-REFUND: 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. .. ### BEGIN~OF~TABLE ### .. _SendURL-for-pi2: SendURL for pi2 """"""""""""""" .. container:: table-row Property SendURL for pi2 Data type string Description **Heidelpay XML--URL** : The XML Transaction will be send to this URL. The default URL is a test URL for standard transaction testing. Default test.ctpe.net/payment/ctpe *[\*without blanks!\*]* .. _errorPageCreditCardRefund: errorPageCreditCardRefund """"""""""""""""""""""""" .. container:: table-row Property errorPageCreditCardRefund Data type string Description **ShopAPI--CC Refund error page** Identifier (PID or alias) of your TYPO3 shop page where the user should be redirected for further processing after error occured during the ePayment creditCard Refund transaction. Default .. _sendWithoutShow: sendWithoutShow """"""""""""""" .. container:: table-row Property sendWithoutShow Data type string Description **ShopAPI--CC Refund return page** Identifier (PID or alias) of your TYPO3 shop page where the user should be redirected for further processing after completing the ePayment creditCard Refund transaction. Default .. _templateFileRefund: templateFileRefund """""""""""""""""" .. container:: table-row Property templateFileRefund Data type file Description **Refund display template** The template file to be used for the refund display of plugin pi2 (template for the Smarty templating engine). Default pt\_heidelpay/res/smarty\_tpl/refund.tpl.html .. _CSS-DEFAULT-STYLE: \_CSS\_DEFAULT\_STYLE """"""""""""""""""""" .. container:: table-row Property \_CSS\_DEFAULT\_STYLE Data type Description :: _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;} ) Default *(see description)* .. ###### END~OF~TABLE ###### [PT\_HEIDELPAY:XMLREFUND] .. _Known-problems: Known problems -------------- - Testing the heidelpay Extension with real valid Credit Card number and wrong valid month respective year creates 'OK' in the TESTING MODE from heidelpay. Heidelpay only checks formal criteria for the CreditCard Input but does not send the transaction to the credit card company in the TESTING MODE. - Asking for this problem (in May 2007), heidelpay only told us that the XML Interface is technically possible but should not be used according to the PCI guidelines of the Credit Card Companies. We are investigating further for this problem. - For testing the WPF Interface it is necessary that your Website is reachable form outside. - For the WPF Interface in DEFAULT Mode Javascript is needed. If Javascript is disabled and **Heidelpay--Frontend WPF-LIGHT** is set to truethe WPF Interface is calle in WPF\_LIGHT Mod . In this case the frontend is embedded in the site and Customer data will be shown. - Another important problem is, that heidelpay does no check for credit- card data in WPF\_LIGHT Mode. Especially if they required fields are filled, because all checking from heidelpay in the frontend is done via Javascript. This could produce transaction costs for the merchant, because in this case heidelpay send the transaction directly to the credit card company without doing any checking. By asking heidelpay for this problem, the reply was that nothing could be done for this (may 2007). - frontendShopName Parameter doesn't work now (maybe in LIVE account we will investigate in this) - frontendHeight doesn't work in Popup Mode correct (because first full information comes up, after that only the block specified in Javascript function will be displayed. To-Do list \- A wish list of things you want to add or fix. This includes smaller problems/bugs which are best described as a todo item. \- Visions for what the extension could become with more development. .. _Changelog: Changelog --------- - 0.1.0 Include WPF Interface for heidelpay - 0.1.1 New Parameters for WPF Interface. Multilanguage support (only for sys\_language not for multiTreeLanguage) - 0.1.2 prefix for session array generalized - 0.1.3 Disable WPF-light for Javascript disabled, if flag is set. Set Frontend closing or redirect Timeto 0, because otherwise the user can change his input after we have got the error Message for heidelpay. |img-1| EXT: heidelpay ePayment - 16 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102