
xt:Commerce 3.0.4 SP2.1
Micropayment HandyPay IPN (Event) Zahlungsmodul V1.1 Stand: 16.02.2009

Autor: Michael Cici (info@skyline-service.de) - http://www.skyline-service.de
Micropayment: http://www.micropayment.de


     * Einleitung
     * Bekannte Probleme
     * Funktionsweise
     * Installation
     * Konfigurationseinstellungen
     * Micropayment Status
     * Micropayment-Account-Einstellungen
     * Zusatzfunktion
     * Sicherheit erhhen - .htaccess
     * Developer Notes



==========
Einleitung
==========

Auf besonderen Wunsch habe ich fr den xt:Commerce die Schnittstelle fr den xt:Commerce-Shop
erstellt. (Als Basis diente Henri Schmidhuber's Modul fr sofortueberweisung.de, das er 
fr xt:c entwickelt hat.)

Persnlich nutze ich aber das osCommerce-Shopsystem, da ich dieses seit fast 5 Jahren in 
diversen Projekten nutze und eigene Contributions dafr mache.
Ich schreibe das jetzt an dieser Stelle nicht, um xt:c schlecht oder Werbung fr osC zu machen,
sondern nur, dass diese Version im Gegensatz zu der erhltlichen osC-Version nicht ganz so 
ausgereift ist, da xt:c doch in der Programmierung mit den Jahren von osC abgewichen ist, auch 
wenn es seinen Ursprung unter osC fand ("The exchange Projekt / osCommerce" 2001-2003).

Der Leistungsumfang des Moduls unter osC <> xt:c ist aber trotzdem fast identisch.

Die Schnittstelle wurde zwar ausgiebig getestet und luft auch zufriedenstellend, doch gibt es 
ein bekanntes Problem, das ich bis jetzt noch nicht lsen konnte.

Wenn also jemand diese Contribution in die Finger bekommt und diese Probleme beheben knnte,
dann wrde es mich freuen, wenn er mich informiert und wir diese Version in der nchsten 
Aktualisierung entsprechend fr Alle verbessern knnten.
Bitte eine eMail an mich (info@skyline-service.de), wer mir seine Hilfe anbieten kann.


=================
Bekannte Probleme
=================

Derzeit keine bekannten Probleme.


==============
Funktionsweise
==============

Das Micropayment-Modul ermglicht es Ihnen, Zahlungen ber den genannten Drittanbieter
abwickeln zu lassen und so dem Kunden eine grere Auswahl an Zahlungsmglichkeiten zu bieten.

Mit allen Zahlungsmglichkeiten von Micropayment erhalten Sie direkt vom Micropayment-Server 
einen Status, der eine Zahlung authorisiert hat, oder nicht.

Ist eine Zahlung authorisiert worden, knnen Sie umgehend die gekaufte Ware versenden und der
Kunde muss nicht die Tage abwarten, bis die Bank die berweisung gebucht hat.
Wenn Sie alternativ downloadbare Artikel anbieten, kann so der Kunde direkt nach Zahlung seine
gekauften Artikel herunterladen

Beachten Sie aber, dass bei Lastschrift(ELV) und CreditCard(CC) der Kunde im Gegensatz zu
einer berweisung innerhalb einer bestimmten Frist die Zahlung wieder zurckgehen lassen kann.
Dies stellt natrlich einen gewissen Risikofaktor dar.

Micropayment nutzt ein Siegel (seal-Parameter) um die bergebenen Variablen (Preis, 
Kundennummer, Bestellnummer, usw.) zustzlich zu verschlsseln.
Somit knnen die bergebenen Variablen nicht so leicht manipuliert werden.
Das Modul arbeitet unverschlsselt und verschlsselt. Allerdings ist letztere Variante auf 
jeden Fall vorzuziehen.

Weitere Informationen zur verschlsselten Micropayment-Zahlung erhalten Sie direkt auf 
https://www.micropayment.de

Dieses Modul wurde so einfach wie mglich gehalten, damit auch Anfnger damit zurecht kommen 
sollten. Alle Informationen, die fr das Modul bentigt werden, werden bequem im 
Administrationsmen eingetragen.

Das Modul kommt ohne die Notwendigkeit aus, nderungen am Shopsystem vornehmen zu mssen.
Es sollte sich daher mit allen mglichen verbauten Contributions einwandfrei vertragen.


============
Installation
============

Die Installation ist kinderleicht. Doch bevor sie beginnen, SICHERN SIE ZUERST UNBEDINGT 
IHR GESAMTES SHOPVERZEICHNIS UND AUCH DIE DATENBANK IHRES SHOPS.

Danach kopieren Sie einfach alle Dateien in der Verzeichnisstruktur auf Ihren Server.

Alle Dateien sind neu und berschreiben keine vorhandenen Original-xt:c-Dateien.

Melden Sie sich danach mit Ihrem Adminstrations-Account in Ihrem Shop an und gehen Sie in
Ihren Admin-Bereich.

Whlen Sie dort auf der linken Seite den Eintrag "Zahlungsoptionen" unter dem Menuepunkt 
"Module" aus.

Sie sehen nun eine Liste aller mglichen Zahlungsmodule die Sie installieren knnen.

Whlen Sie nun das Modul fr HandyPay aus und klicken Sie auf der rechten Seite 
"Installieren".

Nun wird das Modul installiert und Sie knnen die einzelnen Einstellungen vornehmen.


===========================
Konfigurationseinstellungen
===========================

- Micropayment (HandyPay) Modul aktivieren
Ist der Wert "True", kann der Kunde diese Zahlungsart auswhlen.


- Erlaubte Zonen
Geben Sie hier die Zone ein, in welcher HandyPay genutzt werden darf.
(Wenn Sie das Modul live nebenbei testen mchten, knnen Sie ein "Testland"
anlegen und mit einem Testbenutzer, der in einem Land lebt, welches zu 
"Testland" gehrt, knnen Sie experimentieren, ehe Ihre Kunden das Zahlungsmodul 
auswhlen knnen, bis es vollstndig nach Ihren Wnschen arbeitet.)


- Kundennummer
Hier mssen Sie Ihre Micropayment-Account-Nummer (Kundennummer) eintragen.


- Projektkuerzel
Hier mssen Sie den Projekt-Code eintragen, den Ihnen Micropayment fr ein 
neues Projekt vergeben hat. (Beispielsweise: Auto-Seite = ausei = Projektkuerzel)


- Ihr AccessKey
Ihr persnlicher Access-Key, den Ihnen Micropayment generiert hat.
Diesen finden Sie auch in Ihrem persnlichen Kontobereich bei Micropayment.
Sie bentigen diesen Accesskey um verschlsselte Zahlungen an den Micropayment-Server mit 
Hilfe des seal-Parameters bermitteln zu knnen.


- Steuerzone
Wenn eine Zone ausgewhlt ist, gilt die Zahlungsmethode nur fr diese Zone.


- Transaktionswhrung
Nur Euro mglich


- Seitendesign - Template
Micropayment bietet Ihnen eine vielfltige Auswahl an Templates an, die Sie an Ihr Site-Design 
anpassen knnen. Geben Sie hier den Wert (beispielsweise "l3") ein, oder lassen Sie das Feld 
leer um das Standard-Design zu nutzen.
Weitere Informationen, welche Variablen mglich sind, finden Sie bei Micropayment in Ihrem 
Kontenbereich.


- Seitendesign - eigenes Logo/Grafik
Micropayment bietet Ihnen eine vielfltige Auswahl an Grafiken. Auch knnen Sie eine eigene 
Grafik oder ein Logo einbinden. Geben Sie hier den Wert (beispielsweise "x-clouds") ein, oder 
lassen Sie das Feld leer um das Standard-Design zu nutzen.
Weitere Informationen, welche Variablen mglich sind, finden Sie bei Micropayment in Ihrem 
Kontenbereich.


- Temporrer Bestellstatus
Bestellstatus fr noch nicht abgeschlossene Transaktionen.


- Unbesttigter Bestellstatus
Order Status nach Eingang einer Bestellung bei der keine oder eine fehlerhafte 
Zahlungsbesttigung bermittelt wurde.


- besttigter Bestellstatus
Order Status nach Eingang einer Bestellung, bei der von Micropayment eine erfolgreiche 
Zahlungsbesttigung bermittelt wurde.


- Anzeigereihenfolge
Bieten Sie mehrere Zahlungsmglichkeiten an, legen Sie mit Hilfe von Nummern die 
Rangreihenfolge der Zahlungsmglichkeiten fest. Die kleinste Ziffer wird zuerst angezeigt.


- Debug E-Mail Address
Alle Parameter einer ungueltigen IPN-Informierung, so wie eines Stornos oder eines Backpays 
werden per eMail an diese Adresse gesendet, wenn eine eingetragen ist.


- Mindestsumme um HandyPay nutzen zu koennen
Tragen Sie hier die Summe ein, ab welcher Summe dieses Zahlungssystem dem Kunden zur 
Verfgung stehen soll. (HandyPay-Standard-Minimum betrgt 0.49 Euro)
Volle Summen knnen Sie ohne Nachkommastellen eintragen, ansonsten mssen Sie unbedingt 
den Punkt als Komma verwenden. (50, 0.49, 2.50, 100)


- Maximalsumme um HandyPay nutzen zu koennen
Tragen Sie hier die Summe ein, bis zu welcher Gesamtsumme dieses Zahlungssystem dem Kunden 
zur Verfgung stehen soll. (HandyPay-Standard-Maximum betrgt 4.99 Euro)
Volle Summen knnen Sie ohne Nachkommastellen eintragen, ansonsten mssen Sie unbedingt den 
Punkt als Komma verwenden. (50, 0.49, 2.50, 100)


===================
Micropayment Status
===================

Micropayment sendet derzeit drei verschiedene Statusarten:

    * billing: Der Zahlungsbetrag wurde von Micropayment freigegeben.

    * storno: Der Zahlungsbetrag wurde von Micropayment widerufen.
      Dies geschieht beispielsweise dann, wenn der Kufer einen Lastschriftbetrag innerhalb 
      der gesetzlichen 6-Wochen-Frist zurckgehen lsst und Micropayment den Vorgang prft.

    * backpay: Ein Zahlungsbetrag der zuvor den Status "storno" hatte, wurde von Micropayment 
      wieder freigegeben.

Dieses Modul verarbeitet jeden Status und setzt automatisch entsprechend den Bestellstatus
(Temporrer Bestellstatus, Unbesttigter Bestellstatus, Besttigter Bestellstatus)

    * billing = Besttigter Bestellstatus
    * storno  = Unbesttigter Bestellstatus
    * backpay = Besttigter Bestellstatus


==================================
Micropayment-Account-Einstellungen
==================================

    * Sie mssen bereits ein Projekt angelegt haben und dieses muss auch von Seiten 
      Micropayment bereits freigegeben sein.

    * Klicken Sie "Meine Konfiguration" an und wechseln Sie in Ihre Projektliste.

    * Whlen Sie das entsprechende Projekt aus und klicken Sie auf den Button "Aktionen" und 
      whlen Sie dort den Menpunkt "Zahlungsarten konfigurieren" aus.

    * Whlen Sie in der Zahlungsmglichkeiten-Liste den Punkt "HandyPay - Event" aus. 
      (Nicht "HandyPay - File").

    * Klicken Sie nun wieder den Button "Aktionen" und whlen "konfigurieren" aus.

    * Tragen Sie nun in das obere Feld "API-URL" die URL zu Ihrer API ein: 
      "https://www.Ihre_URL.de/xtcommerce/ext/modules/payment/micropayment_hp_ipn/micropayment_hp_ipn.php

          o Seiten mit Full-SSL: https://www.Ihre_URL.de/
          o Seiten mit Shared-SSL: https://sslserver.xssl.de/Ihre_URL.de/

    * Unter "Optionen : Erweiterte Sicherheit" whlen Sie den Punkt 
      "erweiterte Sicherheit aktivieren" aus.

    * Unter "Optionen : API-URL" whlen Sie den Punkt "Das senden zustzlicher Daten 
      aktivieren" aus.

    * ffnen Sie mit Hilfe des "+"-Symbols den Punkt "zustzliche GET-Parameter (QueryString)" 
      und erweitern Sie den Querystring um drei weitere Felder (die letzten drei aus der 
      folgenden bersicht).
      Im Anschluss muss das Ganze so aussehen:

      amount      =     __amount__
      title       =     __title__
      auth        =     __auth__
      country     =     __country__
      currency    =     __currency__
      customerid  =     __$customerid__
      orderid     =     __$orderid__
      XTCsid      =     __$XTCsid__

    * Setzen Sie noch ein Hkchen bei "Zahlungsart aktivieren fr ..."


==============
Zusatzfunktion
==============

Generell versendet das Modul an den Kunden bei erfolgreicher Zahlung die bekannte xtc-Rechnung.

Darber hinaus knnen Sie auch eine zustzliche eMail versenden in dem der Kunde passend zu
seiner Bestellnummer die Micropayment-Transaktions-ID zugesendet bekommt.

Wenn Sie dies nutzen mchten, ffnen Sie hierzu mit einem Texteditor die Datei unter 

"/xtcommerce/ext/modules/payment/micropayment_hp_ipn"

und suchen Sie die Zeile 
    define('MODULE_PAYMENT_MICROPAYMENT_HP_IPN_EMAIL_PAY_SUCCESS', 0); // Hinweis: 0 = generell keine Bestaetigungs-eMail versenden | 1 = Bestaetigungs-eMail versenden
und setzen den Wert von 0 auf 1.

Wenn Sie textliche Anpassungen und/oder Zusatzinformationen in dieser eMail unterbringen
mchten, stehen Ihnen dafr die Zeilen

    define('MODULE_PAYMENT_MICROPAYMENT_HP_IPN_EMAIL_PAY_SUCCESS_ADD_BEFORE', "Sehr geehrter Kunde, sehr geehrte Kundin,<br /><br />Wir bedanken uns fuer Ihren Einkauf.<br />Ihre Zahlung wurde bestaetigt und Ihre bestellten Artikel werden umgehend an Sie versendet.<br /><br />"); // Dies ist ein erweiterbarer Zusatztext (Anfang) in der eMail.
    define('MODULE_PAYMENT_MICROPAYMENT_HP_IPN_EMAIL_PAY_SUCCESS_ADD_AFTER', "Mit freundlichen Gruessen,<br /><b>Ihr Shopbetreiber</b><br />"); // Dies ist ein erweiterbarer Zusatztext (Ende) in der eMail.

zur Verfgung.
Den Text knnen Sie mit HTML-Tags formatieren. (Achten Sie darauf, dass " innerhalb Ihres 
Textes mit einem \ maskiert (\") werden mssen.)

Speichern Sie danach die Datei und legen Sie diese wieder auf Ihrem Server im gleichen
Verzeichnis ab.


==============================
Sicherheit erhhen - .htaccess
==============================

Das Zahlungsmodul verfgt ber einige Sicherheitsmechanismen, damit diese Scripte nicht 
einfach so angestoen werden knnen. Ein mglicher Angreifer braucht mehrere Variablen, die 
im Verhltnis zueinander passen und auch so in Ihrer Shopdatenbank als Auftragsposition 
hinterlegt sein mssten, um erfolgreich zu sein.
Verwenden Sie zustzlich noch den seal-Parameter (dringend empfohlen), sinkt die 
Wahrscheinlichkeit eines Manipulationsversuchs drastisch.

Wer aber noch einen Schritt weiter gehen mchte, sollte das Verzeichnis 
"micropayment_hp_ipn" unter "/xtcommerce/ext/modules/payment/" mit einer .htaccess-Datei versehen, 
damit nur noch der Micropayment-Server die Erlaubnis besitzt, um auf das dort fr ihn 
hinterlegte Script zugreifen zu knnen.

Der Inhalt der .htaccess ist wie folgt:

Order deny,allow
Deny from all
Allow from service.micropayment.de
Allow from proxy.micropayment.de
Allow from access.micropayment.de

Speichern Sie diese Datei als reine Textdatei ab und hinterlegen Sie diese dann in dem 
Ordner "micropayment_hp_ipn" unter "/xtcommerce/ext/modules/payment/".

Hinweis: 
Unter Verwendung eines Shared-SSL-Zertifikats gibt es wohl Probleme mit einer .htaccess-Datei
die einen exclusiven Zugriff fr den Micropayment-Server gestatten soll, da hier wohl der 
SSL-Proxy mit seiner eigenen IP die API anstsst und nicht mit der IP des Micropayment-Servers.
An einer Lsung des Problems suche ich noch. Wer eine Lsung hat ... bitte eine eMail an mich.


===============
Developer Notes
===============

"\ext\modules\payment\micropayment_hp_ipn\micropayment_hp_ipn.php"

micropayment_hp_ipn.php prft die Rckgabeparameter fr Rechnungsnummer, Rechnungswhrung, 
Betrag und Kundennummer mit den Werten aus der Shopdatenbank.
Stimmen diese nicht berein, wird als Status ein "error" ausgegeben und wenn eine 
Debug eMail-Adresse in der Konfiguration hinterlegt wurde, werden an diese alle Parameter 
bermittelt.

Stimmen die Werte berein ("ok") beginnt eine weitere Prfung nach dem bergabestatus 
(billing|storno|backpay) und entsprechend werden dann einzelne Aktionen ausgefhrt 
(E-Mails versendet, Bearbeitungsstatus gendert, etc.)
Im Anschluss geht es dann per Weiterleitung auf die gewohnte "checkout_success.php" Ihres 
Shops.


"\includes\modules\payment\micropayment_hp_ipn.php"

Dieses Script bernimmt den Versand der Parameter zu Micropayment und enthlt ferner die 
Installationsroutinen des Zahlungsmoduls.
