Mention®PayPal Connector

Voraussetzungen

Zum Betrieb von mention® PayPal Connector, nachfolgend Connector benannt, benötigen Sie eine aktivierte PayPal-API mit Zugriff via SOAP (API- und IPN-Daten) innerhalb Ihres PayPal-Accounts.

Installation

Zur Installation starten Sie die Datei mentionPayPalConnector.msi und folgen einfach den Anweisungen des Installationsassistenten. Nach Abschluss der Installation legen Sie die von uns erhaltene Lizenzdatei im Programmverzeichnis ab.

Konfiguration

Vor dem Betrieb muss der Connector konfiguriert werden. Dabei werden die PayPal SOAP API sowie Ihre Datenbankparameter benötigt. Die Konfiguration kann in der Windows Eingabeaufforderung (cmd.exe) mit folgendem Aufruf durchgeführt werden:

"c:\Program Files (x86)\mention Software GmbH\PayPalConnector\PayPalConnector.exe" -m

Darauf erscheint die Menü-Auswahl vom Connector:

Mit der Auswahl d werden die Zugansgdaten der zu verwendenen mention® Datenbank eingetragen. Anschließend wird ein Verbindungstest durchgeführt. Sind die Zugangsdaten korrekt, wird die Tabelle PP_Transactions angelegt, sofern noch nicht vorhanden.

Mit der Auswahl a werden die PayPal API SOAP Zugangsdaten hinterlegt. Benötigt werden der Benutzername, das Passwort sowie die Signatur. Die Angaben Endpoint und Version können mit Enter vorausgewählt und brauchen i.d.R. nicht geändert zu werden. Sind die Zugangsdaten korrekt hinterlegt, wird ein Verbindungstest durchgeführt:

Mit der Auswahl m kann eine Mandantennummer hinterlegt werden. Ist kein Mandant angegeben, wird standardmäßig Mandant 1 verwendet.

Optionale Angabe einer laufenden Banknummer

Ab Connector Version 1.3 kann eine laufende Banknummer des ausgewählten Mandanten angegeben werden, wenn ein in der Automatik abweichendes Konto zur Buchung verwendet werden soll. Wird keine Nummer angegeben, wird standardmäßig das in der Automatik zugewiesene Konto verwendet.

Einstellung in der Warenwirtschaft (dsmain.exe)

Nach der Installation des Connectors ist es erforderlich, in der mention® Warenwirtschaft einige Optionen zu aktivieren.

In Voreinstellungen => Mandanten => Voreinstellungen Verkauf... => Register Buchh. 2 die Option Daten zur Bearbeitung speichern: alle auswählen sowie die Einstellung Separates Einlesen/Bearbeiten von Kontoauszügen aktivieren.

Der Einlesevorgang selbst erfolgt dann mit Bearbeiten => offene Posten => Kontoauszüge => Kontoauszüge einlesen Automatik...

Im Eintrag Intervall wird angegeben, nach wie vielen Minuten die Automatik die vom Connector neu abgerufenen Transaktionen aus der Datenbank einlesen soll. Die automatische Zuordnung einer eingelesenen Transaktion zu einem Beleg erfolgt nach folgenden Kriterien:

1. nach Zahlungsnummer/Transaktionscode + Betrag - gesucht wird im Beleg in den Feldern Zahlungsreferenznummer / externe Referenz 1-3 / Kunden-Bestellnummer / Bezugnahme 2.
2. nach InvoiceID + Betrag - gesucht wird im Feld externe Referenz 1-3.
3. nach E-Mail-Adresse + Betrag

Die zugeordneten und gebuchten Zahlungen/Transaktionen kann man sich über Bearbeitung => Offene Posten => Zahlungseingangsbelege anzeigen lassen.

Import der Zahlungen nach Finance (dsfina.exe)

Die gebuchten Zahlungen müssen nach Finance (dsfina.exe) importiert werden. Das kann z.B. am nächsten Tag erfolgen.

Vor dem ersten Import muss unter Voreinstellungen => Konten für den Import ein Konto für die Paypal-Gebühren hinterlegt werden.

Der Import der Zahlungen erfolgt im gleichen Dialog und auf dieselbe Art wie der Import von Rechnungen in der Warenwirtschaft (dsmain.exe): Bearbeiten => Import => Buchungen. Als Importart wird Zahlungen Debitoren PayPal-Automatik ausgewählt. Periode, Buchungsdatum und Stapel sind genau so anzugeben wie beim Rechnungsimport. Der dabei erstellte Stapel muss anschließend verarbeitet werden, so dass die Zahlungen tatsächlich auf den Konten erscheinen.

Sollte der Stapel versehentlich gelöscht werden, kann der Importvorgang für den entsprechenden Zeitraum wiederholt werden. Allerdings ist zu beachten, dass Zahlungsbuchungen nur einmal verarbeitet werden und bei einer Wiederholung des Imports bereits verarbeitete Buchungen noch einmal gebucht werden.

Die durch die Automatik nicht zugeordneten und gebuchten Zahlungen müssen mit Bearbeitung => Import => Kontoauszüge... => gespeicherte KA bearbeiten => neue Importart => PayPal-Mention zugeordnet und gebucht werden.

Wie bei allen anderen Zahlungen werden diese nachträglich zugeordneten und gebuchten PayPal-Zahlungen erst nach dem Verarbeiten in der Warenwirtschaft gespeichert.

Hinweis: Wenn die PayPal-Zahlungen automatisch eingelesen werden, bitte mehr das manuelle Verfahren für die PayPal-Zahlungen benutzen. Ferner können die in die Warenwirtschaft exportierten Stapel aus Finance nicht zurück in FInance importiert werden. Genauso verhält es sich auch umgekehrt: Die in der Warenwirtschaft gebuchten Zahlungen, die in Finance importiert wurden, werden beim Stapelverarbeiten nicht noch einmal in die Warenwirtschaft geschrieben.

Windows® Aufgabenplanung

Das regelmäßige Abrufen von Transaktionen durch den Connector kann mit der Windows® Aufgabenplanung erreicht werden. Dazu wird eine Aufgabe erstellt, die in einem bestimmten Zeitintervall ausgeführt werden soll (getriggert). Die Aufgabenplanung kann in der Eingabeaufforderung mit dem Befehl taskschd.msc aufgerufen werden. Siehe auch http://technet.microsoft.com/de-de/library/cc721931.aspx.

Nachdem die Aufgabenplanung gestartet wurde, klicken Sie im rechten Abschnitt auf Aufgabe erstellen...

Im Register Allgemein tragen Sie einen Namen für die Aufgabe ein:

Anschließend wird ein neuer Trigger erstellt, der die Zeitsteuerung der auszuführenden Aufgabe enthält (Register Trigger):

Nun muss noch die auszuführende Aktion / Aufgabe hinterlegt werden. Hier wird das Programm PayPalConnector.exe mit Angabe von zusätzlichen Programmparametern (Argumenten) eingetragen:

Aufrufparameter

-start	Startdatum im Format tt.mm.jjjj
-end	Enddatum im Format tt.mm.jjjj
-h, -help	Hilfe anzeigen
-p, -path	Anwendungspfad anzeigen
-v, -version	Anwendungsversion ausgeben
-db	Datenbankeinstellungen ändern
-api	PayPal API-Einstellungen ändern
-g, -get	PayPal-Transaktionen einlesen
-log	Inhalt des Logfiles anzeigen
-nolog	keine Meldungen ins Logfile schreiben
-echo	Meldungen des Connectors in der Konsole ausgeben
-notime	Zeitmessung ausschalten
-nodetail	keine zusätzlichen Detail einer Transaktion abrufen
-debug	zusätzliche Debug-Meldungen aktivieren
-noxml	kein XML in der Datenbank (Tabelle KAEINLXML) speichern
-id	eine einzelne Transaktion auf der Konsole ausgeben (es erfolgt keine weitere Bearbeitung)
-ipn	den PayPal IPN Listener aufrufen (dieser muss vorher konfiguriert werden: PayPalConnector.exe -m und PayPal IPN (Taste "i") wählen)
-pendingdays	Anzahl der Tage, wie weit zurückliegende Transaktionen mit Status "Pending" (offen) auf "Completed" (abgeschlossen) abgefragt werden sollen
-revisiondays	Anzahl der Tage, wie weit zurückliegende Transaktionen abgerufen und mit schon in der Datenbank gespeicherten Transaktionen abgeglichen werden sollen
-mandant	eine Mandantennummer hinterlegen oder ändern
-f, -file	eine Textdatei mit zeilenweisen Transaktionsnummern einlesen und zur weiteren Verarbeitung in mention bereitstellen

Aufrufbeispiele

PayPalConnector.exe -get	Transaktionen ab dem letzten Abrufdatum abrufen. Verwendet aktuelles Datum, wenn noch keine Transaktionen abgerufen wurden.
PayPalConnector.exe -g -start 01.01.2020 -echo	Transaktionen ab 1.1.2020 abrufen und Konsolenausgabe aktivieren
PayPalConnector.exe -id 1234ABCDE4567	Transkation mit ID 1234ABCDE4567 abrufen und anzeigen
PayPalConnector.exe -f transactions.txt	Datei transactions.txt einlesen und die dort enthaltenen, zeilenweisen Transaktionsnummern abrufen und verarbeiten

Changelog

Datum	Version	Changelog
07.01.2013	1.0.0.80	Hinterlegung einer Mandantennummer (mention ab V2012.4)
31.07.2013	1.0.0.86	Datensatz in Tabelle KAEINLXML nur speichern, wenn es Transaktionen/XML gibt, um leeres Feld xDatei zu vermeiden
18.10.2013	1.0.0.91	Feld kaeinlxml_id in Tabelle pp_transactions hinzugefügt, auch Transaktionen speichern, bei denen Call GetTransactionDetails fehlschlägt
02.12.2013	1.0.0.93	Timeout Wert für MSSQL Server sowie SOAP Binding SendTimeout Werte in config exe hinzugefügt
06.12.2013	1.0.0.94	Mandantennummer zu jeder Transaktion speichern, Abfrage des letzten Transaktionsdatums mandantenabhängig
16.01.2014	1.0.0.95	Transaktionen mit Textdatei einlesen korrigiert, Logausgaben bei Revisionsabruf erweitert
21.01.2014	1.0.0.96	Tabellenindex erweitert (PP_Transactions - TransactionID, Betrag, Datum, PaymentStatus) fix: EndDateSpecified auf true setzen bei TransactionSearch Trigger für Tabellenfeld status_date entfernt
27.01.2014	1.0.0.97	Web exception bei Revisionsabruf abfangen, Abrufdatum von pending und revision requests in separaten Dateien ablegen Update Detailtransaktionsdaten bei Revision, bestimmte Payer Namen für den Detailabruf ausschließen
14.02.2014	1.1	Versionierung geändert alle Ergebnisse bei call transactionsearch mit id berücksichtigen (bisher nur letztes Ergebnis) Transactionsearch auch mit invoice id
07.08.2014	1.3	Hinterlegung einer laufenden Banknummer eines Mandanten möglich zur Übergabe an die Automatik
30.09.2014	1.4	fix: fehlender Parameter bei formatierter Stringausgabe bei Statusprüfung (Aufrufparameter pendingdays) kein Detailabruf bei Paymentstatus "Reversal" Transaktion nach erneuter Statusprüfung nur bei Statusänderung in Tabelle KAEINLXML eintragen
12.05.2016	1.7	Auktionskäufername auslesen und übergeben
23.05.2016	1.8	Land und Käuferbetreff auslesen und übergeben
02.06.2016	1.9	autorisierte Transaktionen nicht als buchungsrelevant betrachten
17.10.2016	2.0	add: Transaktionsrückerstattungen (refund transaction)
13.03.2017	3.0	add: Multiaccountfähigket mit mehreren Programminstanzen fix: Fehler beim Deserialisieren des Textkörpers für Vorgang "GetTransactionDetails"
26.09.2017	3.0	fix: Transaktionen mit Status 'Canceled' nicht berücksichtigen
04.07.2018	3.1	TLS 1.2 beim API-Zugriff verwenden
09.07.2019	3.3	fix: Unbekannter Empfänger bei Rückzahlung
05.12.2019	3.4	add: Empfänger E-mail-Adresse bei Rückzahlungen über die Paypal Api in den mention Verwendungszweck bringen
27.05.2021	3.5	add: Feld InvoiceID mit Wert aus zusätzlichen Angaben übergeben