FAQ und Hilfe zur PayPal-API

Beantragen einer PayPal API-Berechtigung

Zur Verwaltung Ihrer API-Daten und sollten Sie bisher noch nie die API-Berechtigung von PayPal genutzt haben und somit noch kein API-Signatur beantragt haben, folgen Sie nun bitte diesen Schritten.

  • Auf der neuen PayPal-Homepage sind die Verkäufereinstellungen leider nicht mehr direkt verlinkt. Aber ein manueller Aufruf ist noch möglich:
    Bitte geben oder kopieren Sie (oder klicken Sie im selben Browser) daher nun die Adresse 
    https://www.paypal.com/businessmanage/credentials/apiAccess
    ein um auf die API-Verwaltung von PayPal zu gelangen

 

Im nächsten Schritt können Sie Ihre "API-Berechtigung verwalten"
Scrollen Sie hierzu runter bis zum Bereich "Benutzerdefinierte Kaufabwicklung" und klicken den Link unter "NVP/SOAP-API-Integration (klassisch)"



Für den Abruf mit Hibiscus wird eine sogenannte "API-Signatur" benötigt
Daher "Fordern Sie eine API-Signatur an" und lassen Sie diese über "Zustimmen und senden" gleich anzeigen

  • Gleich auf der nächsten Seite werden Ihnen nun Ihre notwendigen Daten der API-Signatur angezeigt
    • API-Benutzername
    • API-Passwort
    • Unterschrift

      Klicken Sie hierzu bei allen auf "Anzeigen". Danach können Sie diese Daten mit der Maus selektieren und kopieren
 

Anzeigen der API-Signatur (API-Benutzernamen, API-Passwort und Unterschrift)

Zur Verwaltung Ihrer API-Daten und sollten Sie bisher noch nie die API-Berechtigung von PayPal genutzt haben und somit noch kein API-Signatur beantragt haben, folgen Sie nun bitte diesen Schritten.

  • Gleich auf der nächsten Seite werden Ihnen nun Ihre notwendigen Daten der API-Signatur angezeigt
    • API-Benutzername
    • API-Passwort
    • Unterschrift

      Klicken Sie hierzu bei allen auf "Anzeigen". Danach können Sie diese Daten mit der Maus selektieren und kopieren
 

API-Signaturdaten (API-Benutzername und API-Unterschrift) selbst manuell in Hibiscus eintragen

Zunächst sollten Sie mit dem Kontoanlage-Assistenten ein PaylPal-Konto in Hibiscus angelegt haben.
Tipp: Haben Sie noch keine PayPal-Konto mit dem Assistenten angelegt, können Sie die API-Zugangsdaten gleich dort mit eintragen und die folgenden drei Punkte somit gleich mit erledigen.

  1. Wechseln Sie in Hibiscus in die Detailansicht Ihres PayPal-Kontos

    (das Sie vorher mit dem Kontoanlage-Assistenten erstellt haben)
    bei dem der API-Abruf eingerichtet werden soll

  2. Öffnen Sie über den entsprechenden Button die "Synchronisierungsoptionen" für dieses Konto

  3. Kopieren Sie nun Ihre API-Signaturdaten in die entsprechenden Felder und bestätigen Sie diese mit "Übernehmen"

    (Tipp: Kopieren können Sie ganz einfach wenn Sie den jeweiligen Abschnitt auf der PayPal-Homepage markieren, 
    dann Strg+C zum kopieren drücken, 
    zum entsprechenden Feld in Hibiscus wechseln 
    und dort Strg+V zum Einfügen drücken)

    • Den API-Benutzernamen finden Sie wie im Hauptpunkt Nummer 2 beschrieben (dieser muss ein "_api" enthalten!)
    • Die API-Unterschrift finden Sie ebenfalls wie im Hauptpunkt Nummer 2 beschrieben
    • Das API-Abrufintervall wird in ganzen Stunden angeben und stellt den Zeitraum dar in dem maximal 100 Transaktionen bei PayPal aufgetreten sind
      Je kleiner dieser Wert ist des so länger dauert ein Abruf und je größer der Wert gewählt wird des so schneller wird ein Abruf durchgeführt.
      Sollten Sie keinen oder einen ungültigen Wert eintragen wird automatisch ein Standardwert von 1000 Stunden gesetzt. Dies entspricht 41,6 Tage. Somit sollten bei diesem Beispiel in einem Zeitraum von ca. einem Monat und zehn Tagen in Ihrem PayPal-Account nicht mehr als 100 Transaktionen angefallen sein
    • Mit der letzten Option "API-Synchronisation" können Sie den API-Abruf aktivieren oder durch deaktivieren auf die klassische Abruf-Methode über "ScreenScrapping" wechseln bei der ein Kontoauszug als CSV-Export herunter geladen wird

 

Erläuterung zum API-Abrufintervall von Hibiscus Mashup

Durch Beiträge von Anwendern anderer Homebanking-Programme wurde das Problem angesprochen, dass nicht alle Transaktionen über die PayPal-API abgerufen wurden. 

Dieses Problem entstand daraus, dass man über die PayPal-API pro Abruf- oder Abrufzeitraum maximal 100 Transaktionen zurück geliefert bekommt.

 

Fall-Beispiel der zu diesen Problemen führte:

Nun treten zum Beispiel bei einer Privatperson angenommen 100 Transaktionen in drei Monaten auf und bei einem Unternehmen angenommen 100 Transaktionen in der Woche.

Die Homebanking-Software muss natürlich mit dem kleinsten Zeitraum der möglichen Fälle arbeiten um beide zu unterstützen. Da aber ein Unternehmen natürlich auch mehr als 100 Transaktionen pro Woche produzieren kann wurde dort von der Entwicklung ein fester Abrufzeitraum von einem Tag umgesetzt.

Es wird also für jeden einzelnen Tag ein API-Abruf ausgeführt.

Was ist nun aber wenn ein Unternehmen oder auch eine Privatperson mal über 100 Transaktionen an einem Tag aufweist, zum Beispiel wegen dem Weihnachtsgeschäft?! Es würden alle darüber hinausgehenden Transaktionen nicht abgerufen werden.

Zudem entsteht der Umstand, dass auch bei den Privatpersonen die angenommen doch eigentlich nur 100 Transaktionen im Monaten aufweisen, diese dennoch einen sehr lange Abrufphase hätten da dennoch jeder einzelne Tag für Sie selbst abgerufen wird.

 

Hier soll das flexibel einstellbare Abruf-Intervall in Hibiscus beide Seiten zufrieden stellen und nur die Vorteile nutzen:

Das Abrufintervall wird in Stunden definiert und kann somit auf unter einen Tag, bis eben auf eine Stunde (in der 100 Transaktionen auftreten können eingestellt) oder auf zum Beispiel 1000 Stunden gestellt werden was einen Zeitraum von 41,6 Tagen entspricht.

Fall-Beispiele:

 Privatanwender:  alle sechs Monate kommen nicht mehr als
 100 Transaktionen zu Stande		  das Abrufintervall wird hier auf ca. 4.032 Stunden gestellt
 (24 Std * 7 Tage * 4 Wochen * 6 Monate)
 kleines Unternehmen:  hier werden nicht mehr als 100
 Transaktionen in einer Woche anfallen		  das Abrufintervall wird hier auf ca. 168 Stunden gestellt
 (24 Std * 7 Tage)
 großes Unternehmen:  es kommt sehr oft vor, dass an einem Tag 
 mehr als 100 Transaktionen anfallen		  das Abrufintervall wird auf unter 24 Stunden eingestellt
 (je nachdem in wie viel Stunden 100 Transaktionen anfallen)

Sollte das Abruf-Intervall zu hoch eingestellt sein und in einem Zeitraum des Abrufs doch überraschend mehr Transaktionen als erwartet anfallen wird eine Fehlermeldung ausgeben:

Fehler-Code: 11002: The number of results were truncated. Please change your search parameters if you wish to see all your results.

Hibiscus bricht bei dieser Meldung ab da es gewollt ist, dass alle Umsätze bzw. Transaktionen abgerufen werden. Da es sich hier lediglich um eine Warnmeldung von PayPal handelt kann es vorkommen, dass eine andere Homebanking-Software dies nicht als Fehler meldet und normal weiter arbeitet, dann aber Transaktionen fehlen und somit eine Lücke entsteht. Bei Hibiscus wollen wir dies nicht.

Abhilfe schafft hier dann das Herabsetzen des Abruf-Intervalls.

Es muss hierbei aber immer beachtet werden, dass je niedriger das Abruf-Intervall gesetzt wird des so länger dauert der Datenabruf da der Abrufzeitraum immer in Abschnitte so groß wie das Abrufintervall aufgeteilt wird.

 

Beispiel eines Abrufs von einem Zeitraum von einem Jahr mit einem Abruf-Intervall von 1000 Stunden:

Abrufdatum: 31.12.2013 es wird also der Zeitraum von 01.01.2013 bis 31.12.2013 abgerufen.

Dies löst nun eine Transaktionssuche aus in dem der Abrufzeitraum in 41,6 Tage Abschnitte aufgeteilt wird:

von 01.01.2013 00:00:00  bis  11.02.2013 16:00:00
von 11.02.2013 16:00:00  bis  25.03.2013 08:00:00
....... usw. ......
von 21.02.2014 16:00:00  bis  04.04.2014 09:00:00
von 04.04.2014 09:00:00  bis  15.04.2014 12:01:22

Insgesamt werden hier '12' Zeiträume abgerufen.

Stellt man nun das Stundenintervall auf z. B. 10 herab, dauert der Abruf 100x so lange da dem entsprechend mehr Abschnitte entstehen.

In diesem Beispiel würde ein Abruf von einem Jahr mit relativ wenigen Umsätzen und einem Abruf-Intervall von 10 Std. ungefähr 20 Minuten dauern da ca. 878 Abschnitte abzurufen wären.
Für zwei Jahre verdoppeln sich hier natürlich die Werte usw.

Daher bedeutet dies immer, dass ein Komplett-Abruf bis zu zwei Jahren mit der klassischen Methode sehr wahrscheinlich schneller ist.

Sollten Sie schon einmal die API-Berechtigung von PayPal genutzt haben und eine API-Signatur beantragt haben, folgen Sie nun bitte diesen Schritten um diese anzuzeigen.