osCommerce 2.2 Milestone 2
Micropayment CreditCard IPN (Event) Zahlungsmodul V1.0

Original Autoren: Harald Ponce de Leon, Mark Evans osCommerce Team Members

Autor: Michael Cici - http://www.ebook-tower.de

Micropayment: https://www.micropayment.de

osCommerce: http://www.oscommerce.com

Inhalt

Einleitung

Ich habe dieses Contrib auf Basis von Edith Karnitsch's PayPal_IPN_v2.2-Contrib erstellt.

Es enthält einige Änderungen, da der Ablauf bei Micropayment ein wenig anders ist, als bei PayPal. Die bekannten Probleme bleiben auch in dieser Version offen. Wer möchte, kann sich gerne daran versuchen eine Lösung zu finden.
Wir arbeiteten seit längerem mit der PayPal-Contrib und den bekannten Problemen und konnten damit leben. Ein wenig Handarbeit ist dann im täglichen Ablauf halt notwendig. Im folgenden Kapitel sind die bekannten Probleme aufgelistet.

Aber was macht diese Contrib eigentlich und für was ist sie gut?

OsCommerce-Shops erfordern eine Rückkehr des Kunden vom Zahlungsportal um weitere Details zur Bestellung zu erfassen, um E-Mails zu generieren und Bestandsmengen zu aktualisieren.

In der Vergangenheit hatte der Shopbetreiber ein Problem, wenn ein Kunde nicht wieder auf die Site zurückgekehrt ist nach der Zahlung seiner Bestellung. Der Betreiber bekam einen Betrag erstattet, wusste aber nicht von wem. Dieses Modul behebt dieses Problem, indem es Bestellungen vorzeitig (vor Ausführung der Zahlung unter Zuhilfenahme eines Drittanbieters) in der Datenbank mit einem Bearbeitungsstatus erstellt, und sobald ein Kunde zahlt, wird der Bearbeitungsstatus automatisch vom Zahlungsportal aktualisiert.

Das bedeutet, dass selbst wenn ein Kunde nicht wieder auf die Seite zurückkehrt, alle notwendigen Informationen der Bestellung aufgezeichnet wurden, auch wenn keine Details und E-Mails generiert wurden. Alle dann noch offenen Bestellungen mit dem entsprechenden Bearbeitungsstatus müssen sorgfältig geprüft werden.

nach oben

Bekannte Probleme

nach oben

Wie funktioniert es

Das CreditCard-Modul speichert Bestellungen vorzeitig in der Datenbank, damit diese vom Zahlungsportal verarbeitet werden können. Das Zahlungsportal Micropayment sendet automatisch nach erfolgtem Durchlauf eine Rückantwort an den Shop, damit dieser die Informationen passend zuordnen und verarbeiten kann. Es werden darauf hin e-Mail-Benachrichtigungen versendet, der Warenbestand aktualisiert, der Bearbeitungsstatus geändert, usw.

Mit diesem Modul können Sie unverschlüsselt (nicht empfohlen), so wie mit dem von Micropayment verwendeten seal-Schlüssel (empfohlen) verschlüsselte und somit relativ sichere Zahlungsinformationen an Micropayment senden, die der Käufer nicht manipulieren kann. Die Rückübertragung funktioniert genau so und ist alles stimmig, werden die einzelnen Prozesse automatisiert angestossen. Ungültige Bestellungen muss der Shopbesitzer sorgfältig prüfen.

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

Dieses Modul wurde so einfach wie möglich gehalten, damit auch Anfänger damit zurecht kommen sollten. Alle Informationen, die für das Modul benötigt werden, werden bequem im Administrationsmenü eingetragen.

Das Modul kommt bis auf eine Stelle ohne die Notwendigkeit aus, Änderungen am Shopsystem vornehmen zu müssen. Es sollte sich daher mit allen möglichen verbauten Contribs einwandfrei vertragen.

nach oben

Installieren des CreditCard-Moduls

  1. Wichtig: Machen Sie ein vollständiges Backup Ihres Shops, bevor Sie beginnen!
  2. Kopieren Sie alle Dateien in die Verzeichnis-Struktur Ihres Shops. Das \ext-Verzeichnis ist ein neues Verzeichnis, das hinzu kommt.
  3. Öffnen Sie Ihr osCommerce-Administrations-Menue und wählen Sie "Module->Zahlungsweise" aus.
  4. Installieren Sie das Kreditkartenzahlung (CreditCard)-Modul und konfigurieren Sie die Parameter entsprechend. Hinweis: Das Modul ist im Ursprungszustand abgeschaltet, so dass eine Konfiguration auch in einem Live-Shop erfolgen kann.
  5. Nun müssen wir noch eine kleine Erweiterung in einem Shopscript vornehmen. Öffnen Sie die Datei "\shop\checkout_confirmation.php" und suchen Sie dort nach dem Absatz:

    <?php
      if (isset($$payment->form_action_url)) {
        $form_action_url = $$payment->form_action_url;
      } else {
        $form_action_url = tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL');
      }

      echo tep_draw_form('checkout_confirmation', $form_action_url, 'post');

      if (is_array($payment_modules->modules)) {
        echo $payment_modules->process_button();
      }

      echo tep_image_submit('button_confirm_order.gif', IMAGE_BUTTON_CONFIRM_ORDER) . '' . "\n";
    ?>

    und ersetzen Sie den Absatz mit:

    <?php
      if (isset($$payment->form_action_url)) {
        $form_action_url = $$payment->form_action_url;

        if($$payment->code == "micropayment_cc_ipn") {
          $form_action_url = $form_action_url.$payment_modules->process_button();
        }

      } else {
        $form_action_url = tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL');
      }

      echo tep_draw_form('checkout_confirmation', $form_action_url, 'post');

      if (is_array($payment_modules->modules)) {
        if ($$payment->code != "micropayment_cc_ipn") {
          echo $payment_modules->process_button();
        }
      }

      echo tep_image_submit('button_confirm_order.gif', IMAGE_BUTTON_CONFIRM_ORDER) . '' . "\n";
    ?>

    Im Gegensatz zum PayPal-Modul, das die Parameter per input-type hidden via POST übergibt, übertragen wir die Parameter mittels GET per URL.

    Der modifizierte Abschnitt überprüft jetzt, ob es sich um das Zahlungsmodul CreditCard (micropayment_bp_cc) handelt und falls das zutrifft, erstellt die Funktion process_button() der Klasse Payment nun die Parameter und hängt diese an die Micropayment-URL, anstatt hidden-Felder zu generieren.
    Diese werden dann auch unter "if ($$payment->code != "micropayment_cc_ipn") {" nicht mehr ausgeführt, wenn es sich beim Zahlungsmodul um das CreditCard handelt.

Verwenden Sie mehrere Micropayment-IPN-Module müssen Sie diese natürlich hier auch eintragen.
Beispiel mit Verwendung des eBank2Pay und des CreditCard-Moduls:
<?php
  if (isset($$payment->form_action_url)) {
    $form_action_url = $$payment->form_action_url;

    if($$payment->code == "micropayment_cc_ipn" || $$payment->code == "micropayment_bp_ipn" ) {
      $form_action_url = $form_action_url.$payment_modules->process_button();
    }

  } else {
    $form_action_url = tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL');
  }

  echo tep_draw_form('checkout_confirmation', $form_action_url, 'post');

  if (is_array($payment_modules->modules)) {
    if ($$payment->code != "micropayment_cc_ipn" && $$payment->code != "micropayment_bp_ipn") {
      echo $payment_modules->process_button();
    }
  }

  echo tep_image_submit('button_confirm_order.gif', IMAGE_BUTTON_CONFIRM_ORDER) . '' . "\n";
?>

nach oben

Sicherheit erhöhen - .htaccess

Das Zahlungsmodul verfügt über einige Sicherheitsmechanismen, damit diese Scripte nicht einfach so angestoßen werden können. Ein möglicher Angreifer braucht mehrere Variablen, die im Verhältnis zueinander passen und auch so in Ihrer Shopdatenbank als Auftragsposition hinterlegt sein müssten, um erfolgreich zu sein.
Verwenden Sie zusätzlich noch den seal-Parameter (dringend empfohlen), sinkt die Wahrscheinlichkeit eines Manipulationsversuchs drastisch.

Wer aber noch einen Schritt weiter gehen möchte, sollte das Verzeichnis "micropayment_cp_ipn" unter "/shop/ext/modules/payment/" mit einer .htaccess-Datei versehen, damit nur noch der Micropayment-Server die Erlaubnis besitzt, um auf die dort für ihn hinterlegten Scripte zugreifen zu können.

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_cp_ipn" unter "/shop/ext/modules/payment/".

Alternativ kann man auch mittels PHP die IP-Adresse des Micropayment-Servers ausfiltern, wenn man keine .htaccess-Datei verwenden möchte.
Hierzu ist es notwendig, das Script "/shop/ext/modules/payment/micropayment_cp_ipn/micropayment_cp_ipn.php" zu modifizieren.

Suchen Sie in dem Script nach dem Absatz:

require('includes/application_top.php');


und fügen Sie direkt darunter folgendes ein:
  if (substr($_SERVER["REMOTE_ADDR"],0,12) != "193.159.183.") {
      $status = 'error';
      $email_body = '$_POST:' . "\n\n";
      foreach ($_POST as $key => $value) {
            $email_body .= $key . '=' . $value . "\n";
      }
      $email_body .= "\n" . '$_GET:' . "\n\n";
      foreach ($_GET as $key => $value) {
            $email_body .= $key . '=' . $value . "\n";
      }

      tep_mail('', MODULE_PAYMENT_MICROPAYMENT_CP_IPN_DEBUG_EMAIL, 'Micropayment CP IPN Falsche IP-Adresse', $email_body, STORE_OWNER, STORE_OWNER_EMAIL_ADDRESS);

      $response = 'status=' . $status;
      $response .= $trenner;
      $response .= 'url=' . $url;
      $response .= $trenner;
      $response .= 'target=' . $target;
      $response .= $trenner;
      $response .= 'forward=' . $forward;

      echo $response;
      exit;
  }

Dieser Abschnitt überprüft, ob es sich um die IP-Adresse des Micropayment-Servers handelt.
Ist sie es nicht, werden alle Parameter gesammelt und in eine Informations-eMail gepackt, die Ihnen dann zugemailt wird. Das Script wird umgehend beendet.


Hinweis: Unter Verwendung eines Shared-SSL-Zertifikats gibt es wohl Probleme mit beiden Varianten, da hier wohl der SSL-Proxy mit seiner eigenen IP die API anstösst und nicht mit der IP des Micropayment-Servers.
An einer Lösung des Problems suche ich noch. Wer eine Lösung hat ... bitte eine eMail an mich.

nach oben

Konfigurationseinstellungen (Shop Admin)


Aktiviere Micropayment CreditCard IPN Modul

Ist der Wert "True", kann der Kunde diese Zahlungsart auswählen.


https-Adresse Ihres Shops

Hier müssen Sie die https-URL Ihres Shops eintragen und zwar geben Sie diese bitte ohne ein abschließendes "\", aber mit einem beginnenden "https://" ein.


eMail-Adresse

Ihre e-Mail-Adresse.


Position von CreditCard-Event

Bieten Sie mehrere Zahlungsmöglichkeiten an, legen Sie mit Hilfe von Nummern die Rangreihenfolge der Zahlungsmöglichkeiten fest.


Transaktionswährung

Hier können Sie auswählen, welche Währung akzeptiert wird. Empfohlen ist "Only EUR", zumal Micropayment sowieso nur in Euro abwickelt.


Zahlungszone

Geben Sie hier die Zone ein, in welcher CreditCard genutzt werden darf. (Wenn Sie das Modul live nebenbei testen möchten, können Sie ein "Testland" (Unter Land->Steuer->Steuerzonen) anlegen und mit einem Testbenutzer, der in einem Land lebt, welches zu "Testland" gehört, können Sie experimentieren, ehe Ihre Kunden das Zahlungsmodul auswählen können, bis es vollständig nach Ihren Wünschen arbeitet.)


Preparing Order Status (Standardwert bevor Transaktion abgeschlossen)

Insgesamt haben wir drei Zustände des Status:

Unter "Sprachen/Währungen->Bestellstatus" können Sie diese drei anlegen.
Die Bezeichnungen sind egal, bspw. "MP-Bearbeitung" / "Preparing [ePay]", "MP-Prüfung", und "MP-Download" / "MP-Freigabe" / "MP-Abgeschlossen".

Wenn Sie Download-Artikel anbieten, achten Sie darauf, dass die ID für Preparing Order kleiner ist als die für Acknowledged Order und diese wiederrum kleiner ist, als die für Completed Order. (Siehe hierzu am besten die Informationen zur Contrib "Download Controller".)



Acknowledged Order Status (Standardwert bei unklaren Transaktionen)

siehe "Preparing Order Status"


Completed Order Status (Standardwert nach erfolgreichem Abschluss)

siehe "Preparing Order Status"


Transaktions-Typ

Standardwert: Event

Alle Rechnungspositionen werden zu einer Endsumme gebildet.


MwSt auf Endbetrag addieren?

Wert: True - addiert die Mehrwertsteuer auf den Rechnungs-Endbetrag.

Wert: False - addiert die Mehrwertsteuer nicht auf den Rechnungs-Endbetrag.


Seitendesign - Template

Micropayment bietet Ihnen eine vielfältige Auswahl an Templates an, die Sie an Ihr Site-Design anpassen können. Geben Sie hier den Wert (beispielsweise "l3") ein, oder lassen Sie das Feld leer um das Standard-Design zu nutzen.

Weitere Informationen, welche Variablen möglich sind, finden Sie bei Micropayment in Ihrem Kontenbereich.


Seitendesign - eigenes Logo/Grafik

Micropayment bietet Ihnen eine vielfältige Auswahl an Grafiken. Auch können 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 möglich sind, finden Sie bei Micropayment in Ihrem Kontenbereich.


Debug E-Mail Address

Wenn Sie hier eine E-Mail-Adresse eintragen, werden alle Parameter-Fehler die im Austausch zwischen Ihrer Seite und dem Micropayment-Server auftreten an diese hinterlegte Adresse gesendet.


Project

Hier müssen Sie den Projekt-Code eintragen, den Ihnen Micropayment für ein neues Projekt vergeben hat.


Account

Hier müssen Sie Ihre Micropayment-Account-Nummer (Kundennummer) eintragen.


Access-Key

Ihr persönlicher Access-Key, den Ihnen Micropayment generiert hat.

Diesen finden Sie auch in Ihrem persönlichen Kontobereich bei Micropayment.

Sie benötigen diesen Accesskey um verschlüsselte Zahlungen an den Micropayment-Server mit Hilfe des seal-Parameters übermitteln zu können.


Mindestsumme um CreditCard nutzen zu koennen

Tragen Sie hier die Summe ein, ab welcher Summe dieses Zahlungssystem dem Kunden zur Verfügung stehen soll.

Volle Summen können Sie ohne Nachkommastellen eintragen, ansonsten müssen Sie unbedingt den Punkt als Komma verwenden. (50, 0.49, 2.50, 100)


Maximalsumme um CreditCard nutzen zu koennen

Tragen Sie hier die Summe ein, bis zu welcher Gesamtsumme dieses Zahlungssystem dem Kunden zur Verfügung stehen soll.

Volle Summen können Sie ohne Nachkommastellen eintragen, ansonsten müssen Sie unbedingt den Punkt als Komma verwenden. (50, 0.49, 2.50, 100)


nach oben

Micropayment Status

Micropayment sendet derzeit drei verschiedene Statusarten:

Dieses Modul verarbeitet jeden Status und setzt automatisch entsprechend den Bestellstatus wie Sie sie unter "Acknowledged Order" und "Completed Order" in der Modulkonfiguration (Siehe Abschnitt "Installation") vergeben haben.

nach oben

Micropayment-Account-Einstellungen