Vorabinfo – Technische Besonderheiten die nur für den Abruf von Paypal Kontobewegungen über REST-API gelten:
Bislang wurden PayPal Buchungen ohne programmseitige Filterungen und Ergänzungen so importiert, wie sie von der eingesetzten Bankingkomponente übertragen wurden.
Da die Datenhaltung über REST-API jedoch eine andere ist, war es notwendig programmseitig Anpassungen vorzunehmen um dem Anwender einen Ablauf zu ermöglichen, der dem Ablauf über den klassischen NVP/SOAP-API Zugang ähnelt.
Nachfolgend eine Übersicht der programmseitigen Anpassungen für den Abruf von PayPal Datensätzen über die REST API:
1) Es werden programmseitig Gebühren Datensätze erzeugt (da der Abruf über REST-API keine separate Buchung mehr für die Gebühren liefert)
2) Die Programmroutinen in der Software wurden dahingehend angepasst, dass die neuen Status Bezeichnungen von PayPal Berücksichtigung finden
Diese Status-Bezeichnungen von PayPal finden Sie unter PARAMETER – ABRECHNUNG – ZAHLUNGSVERKEHR PARAMETER – „Vorgabe Status für PayPal Kontoauszüge“.
Ab Update 6740 (veröffentlicht Ende Dezember 2022):
3) Eine programmseitige Filterung der Buchungen („Bookings“) wird unterstützt, damit nicht buchungsrelevante Buchungen (z. B. des Typs T21nn Reserves → auch „Hold“) nicht mehr importiert werden.
Es werden alle Bookings gefiltert, die
eine ReferenzTyp auf eine andere PayPal Zahlung (TXN) haben
UND eine Referenznummer
UND der EventCode nicht mit T11 anfängt
UND die Gebühr nicht leer ist
UND Kein Surname, Givenname oder AlternateFullname enthalten
4) Differenzierung zwischen Gebühr und Zahlung durch Ergänzung der Bezeichnung „Payment“:
Allen PayPal Zahlungen die kein Gebühren-Datensatz darstellen, wird im Verwendungszweck programmseitig das Wort „Payment“ hinzugefügt
5) Event Code und Referenz:
Allen PayPal Buchungen wird im Verwendungszweck der Event Code und wenn vorhanden auch die Referenz hinzugefügt
6) Performance:
Die Routine zum Hinzufügen von PayPal Zahlungen wurde verschnellert
Beachten Sie:
Wir empfehlen Ihnen die Software seitige Umstellung zunächst mit einer weiteren, neuen PayPal Bankverbindung in buhl Unternehmer vorzunehmen und Ihre bestehende PayPal Bankverbindung (die noch über SOAP-API Zugang erfolgt) erst nach einem Test der neuen Bankverbindung neu zu initialisieren. Bitte beachten Sie auch dass durch die abweichende Datenhaltung der Datensätze die in der Software verfügbaren Dublettenfilter nicht greifen können.
WICHTIG: Verzögerte Bereitstellung seitens der PayPal REST-API
Der Abruf über REST-API erfolgt über eine Reporting API. Diese Schnittstelle liefert die Transaktionen mit bis zu drei Stunden Verzögerung, dies kann auch in der Dokumentation von PayPal selbst entnommen werden unter https://developer.paypal.com/docs/api/transaction-search/v1/#transactions_get (externer Link). In der ersten aufgeführten „Notes“ Box ist nachfolgender Hinweis enthalten: „It takes a maximum of three hours for executed transactions to appear in the list transactions call.“
Programmseitig kann kein Einfluss auf diese verzögerte Bereitstellung der Daten über die REST-API genommen werden.
Sollten bei Ihnen zeitkritische Abläufe bestehen, die einen verzögerungsfreien Abruf der Transaktionen erfordern, empfehlen wir Ihnen den klassischen Abruf über PayPal NVP/SOAP-API. DerAbruf über die klassische NVP/SOAP-API erfolgt ohne die Verzögerung von bis zu drei Stunden.
Zugang zur REST-API von PayPal erstellen
Mit den folgenden Schritten erzeugen Sie auf der PayPal Developer Webseite einen Zugang zur PayPal REST-API, den Sie anschließend in der Software für den Abruf der PayPal Datensätze verwenden können:
1) Loggen Sie sich auf https://developer.paypal.com (Externer Link) mit Ihren PayPal Anmeldedaten (PayPal Benutzername bzw. PayPal E-Mail Adresse) ein.
2) Wählen Sie die Rubrik „Dashboard“ aus.
3) Schalten Sie den Regler (oben rechts) auf „Live“ um.
4) Erstellen Sie eine Applikation, indem Sie den Button „Create App“ betätigen.
5) Geben Sie Ihrer Applikation einen eigenen Namen und bestätigen Sie auch hier Ihre Eingabe über den Button „Create App“. Sonderzeichen und Umlaute sind hier nicht möglich.
6) WICHTIG: Aktivieren Sie „Transaction Search“ (Buchungen abrufen) und speichern Sie die Einstellung („Save“-Button).
7) Klicken Sie auf die Schaltfläche: „Show“ und notieren Sie sich die Client-ID sowie das Secret und bewahren Sie diese Informationen an einem sicheren, nur für Sie zugänglichen Ort auf.
Beachten Sie:
- Die Freischaltung durch PayPal kann bis zu 24 Stunden dauern.
- Erst nachdem diese erfolgt ist, können Sie diese Anmeldedaten innerhalb der Software verwenden um eine PayPal Bankverbindung einzurichten.
- Ihr alter PayPal Zugang über SOAP-API bleibt PayPal-seitig weiterhin bestehen.
-
Informationen zum Vorgabe Status für PayPal Kontoauszüge
Infos zum Vorgabe Status für PayPal Kontoauszüge erhalten Sie im Bereich: Zahlungsverkehr Parameter.
Vorgabe Status für PayPal Kontoauszüge
Beim Abruf von PayPal-Kontoauszügen wird von PayPal ein Status mitgegeben. An dieser Stelle haben Sie die Möglichkeit dazu, selbst zu definieren, welcher PayPal-Status beim Abholen / Einlesen der Kontoauszüge einen Datensatz als „Aktiv“ oder „wartet“ kennzeichnet.
Beachten Sie:
Damit die von Ihrer buhl Unternehmer-Software vorgeschlagenen Vorgaben wirksam werden, ist es erforderlich, die Parameter einmal aufzurufen und neu abzuspeichern. Werden diese nicht neu abgespeichert, werden die Einträge nicht beachtet und es gelten weiterhin die bisherigen Routinen zum Einladen.
Als Vorschlag sind folgende Angaben hinterlegt:
| Completed | Aktiv | S | The transaction successfully completed without a denial and after any pending statuses. |
| Pending | Wartet | P | The transaction is pending. The transaction was created but waits for another payment process to complete, such as an ACH transaction, before the status changes to S. |
| Placed | Wartet | (entfallen) | — |
| Removed | Wartet | D | PayPal or merchant rules denied the transaction. |
| Refunded | Wartet | V | A successful transaction was reversed and funds were refunded to the original sender. |
| Partially Refunded | Wartet | F | The original recipient partially refunded the transaction. |
In buhl Unternehmer können Sie zwischen folgenden Status-Angaben wählen:
- Aktiv
- Wartet
- Fehler
- Bearbeitet (OK)
REST-API Zugangsdaten für Ihre bestehende PayPal Bankverbindung verwenden
Um die neu erzeugten REST-API Zugangsdaten für Ihre bestehende PayPal Bankverbindung zu verwenden, gehen Sie bitte wie folgt vor:
1. Erstellen Sie eine aktuelle Datensicherung
2. Begeben Sie sich über die Registerkarte: DATEI – INFORMATIONEN – AKTUELLE FIRMA/FILIALE/MANDANT – MANDANT BEARBEITEN auf das Register: „Bankverbindungen“
3. Rufen Sie Ihre PayPal Bankverbindung zum „Ändern“ auf
4. Wechseln Sie auf das Register: ONLINE BANKING EINSTELLUNGEN und erstellen Sie einen Screenshot des kompletten Registers, damit Sie später auf dieses Abbild der Konfiguration wieder zugreifen können.
Tipp:
Sie können diese Bildschirmaufnahme z. B. über die Taste „Druck“ Ihrer Tastatur auslösen.
Nutzen Sie alternativ z. B. das mit Windows ausgelieferte Bildschirmaufnahmetool (Snipping Tool) oder andere Optionen.
5. Wechseln Sie auf das Register: „Online Banking“
6. Über die Schaltfläche: KONTO EINRICHTEN rufen Sie den Assistenten für die Konto Einrichtung auf und folgen dem Assistenten bis zur Fertigstellung
Nutzen Sie bei der Abfrage der Zugangsdaten die neuen Zugangsparameter „Benutzername„, „Client ID“ und „Secret„
Wählen Sie die Schaltfläche: WEITER und bestätigen Sie die Zusammenfassung mit der Schaltfläche: FERTIGSTELLEN.
7. Kontrollieren Sie im Anschluss die Angaben im Register: ONLINE BANKING EINSTELLUNGEN – diese sollten von Ihnen gegebenenfalls angepasst werden, zum Beispiel: das Datum im Feld: „Letzter Datenabruf“ oder das Kennzeichen: „Doppelte Buchungen über Bankingkomponente filtern“
8. Sollten Sie die „Tresor Verwaltung“ nutzen, ist die neue „PIN“ (= „Secret“) entsprechend zu aktualisieren (auch bei der Umsatzabfrage ist zukünftig bei PIN-Abfrage das neue „Secret“ zu verwenden)
9. Verlassen Sie anschließend alle Fenster über die Schaltfläche: „SPEICHERN & SCHLIESSEN“
Beim Import von PayPal-Kontoauszügen über den Assistenten in buhl Unternehmer wird nun das „Secret“ der API als Passwort abgefragt. Dies lässt sich z. B. auch im Datentresor hinterlegen.
Info:
Informationen zum Vorgabe Status für PayPal Kontoauszüge erhalten Sie in den Parametern im Bereich: Zahlungsverkehr Parameter.