Quick Start Guide - Deutsch

Vor dem Start

Dieser Quick Start Guide führt Sie Schritt für Schritt durch den Setup-Prozess der PAYONE Plattform. Anhand von Beispielen wird die Einrichtung und Konfiguration des Merchant-Accounts, die Nutzung der Schnittstellen und des PAYONE Merchant Interfaces (PMI) vorgestellt.

Die PAYONE Plattform ist modular aufgebaut, um für Ihr Geschäftsmodell das optimale und auf Ihre Bedürfnisse passende Leistungsspektrum zu bieten. Dieser Quick Start Guide führt exemplarisch durch eine Konfiguration – passen Sie sie nach Ihren Bedürfnissen an.

Weiterführende Dokumente helfen Ihnen dabei, zum Beispiel die technischen Referenzdokumente. Sollten Sie doch einmal nicht weiterkommen, hilft Ihnen der PAYONE Merchant Service gerne weiter.

---end

Um die nachfolgend beschriebenen Schritte aktiv nachvollziehen zu können, sollte eine dieser Voraussetzungen erfüllt sein: 
 1

Sie haben Ihren Benutzernamen und Ihr Passwort erhalten (per separater E-Mail, nach Auftragsannahme durch PAYONE). Diese Daten dienen als Login für das PMI, die zentrale webbasierte Ver­waltungsoberfläche der PAYONE Plattform.

---end

 2

Sie haben einen Testzugang erhalten und wollen das Setup unverbindlich ausprobieren.

---end

Schritt für Schritt zur ersten Transaktion

Ein Merchant-Account bei PAYONE umfasst stets mindestens ein Zahlungsportal, einen Sub-Account und mindestens eine Art der Anbindung (Schnittstelle). Zusammen bilden sie das Basissystem. Die hierbeschriebenen Funktionen sind im Test- und im Live-Betrieb verfügbar. Das System ist hierbei gleich, einziger Unterschied ist, dass im Test-Betrieb keine Daten an externe Systeme weitergeleitet werden. Die Antworten (z. B. von Banken) werden – soweit möglich – simuliert. Für zahlreiche Vorgänge bieten wir Testdaten an um ihnen bei der erfolgreichen Testung behilflich zu sein.

Wenn Sie Requests im Live-Betrieb durchführen, so werden diese bei Ausführung auch extern weiter­geleitet – auch mit Testdaten. Wird dabei beispielsweise der Postversand von Dokumenten oder Rücklastschriften ausgelöst, entstehen hierdurch Kosten. Kontrollieren Sie daher stets, ob Sie sich im korrekten Modus befinden, bevor Sie Vorgänge anstoßen.

Für einige Zahlungsarten sind mehr Daten notwendig, als für andere, daher kann es sein, dass der Live-Mode nicht funktioniert. Dieser wird im Service erst dann aktiviert, wenn alle Daten vorliegen und/order sämtliche Riskprüfungen abgeschlossen sind. Anschließend können Sie im Shop in den Live-Betrieb wechseln.

---end

Einrichtung Ihres Merchant-Accounts

Schritt eins auf dem Weg zur ersten Transaktion ist der Login in das PAYONE Merchant Interface (PMI) über die URL https://pmi.pay1.de oder über den Link auf www.bspayone.com (Login -> Merchant Interfaces -> Zum Login).

Die Anmeldung erfolgt über Ihren Benutzernamen und das dazugehörige Passwort, welches nach initialer Anmeldung von Ihnen zu ändern ist. Ihre Merchant-ID, die in der PMI am oberen rechten Rand angezeigt wird, dient als Referenz bei Serviceanfragen und sollte daher bei jedem Kontakt mit PAYONE genannt werden.

Der Link für die Passworteingabe ist nur für 720 min gültig. Danach muss erneut ein Link vom PAYONE Merchant Service generiert werden.

---end

Die Passwörter unterliegen den Passwort-Richtlinien für PCI DSS (Anforderung 8.2.3 ff). D.h.: Mindestens 16 zufällig gewählten Zeichen (Klein- und Großbuchstaben, Sonderzeichen, Zahlen, keine Umlaute, maximal 150 Zeichen). Erneuerung nach spätestens 90 Tagen, Sperre nach maximal 6 Fehlversuchen, die letzten 4 Passwörter müssen unterschiedlich sein, dürfen den Benutzernamen nicht enthalten, müssen nach Erstzuweisung/Passwort-Reset neu gesetzt werden.

---end

Konfiguration eines Zahlungsportals

Jeder Zahlungsvorgang muss innerhalb der PAYONE Plattform einem Zahlungsportal zugewiesen werden. Während des Setup-Prozesses wurde durch das PAYONE Service Team bereits mindestens ein Zahlungsportal für Sie angelegt, welches nun von Ihnen konfiguriert werden muss. Hierzu findet man unter [Konfiguration] den Punkt [Zahlungsportale]. Wählt man diesen aus, erhält man eine Übersicht aller vorhandenen Zahlungsportale.

In Abhängigkeit des gewählten Portals müssen verschiedene Daten eingeben werden, exemplarisch wird hier die Konfiguration eines Portals des Typs Shop gezeigt (siehe Info-Box). Der vom PAYONE Team vergebene Portalname kann durch Sie geändert werden.

Was ist ein Zahlungsportal?

In einem Zahlungsportal sind die Einstellungen zum Zahlungsverkehr und Debitorenmanage­ment hinterlegt. Anhand der Wahl des Zahlungsportals unterscheidet die PAYONE Plattform zwischen zwei Abrechnungsarten:

  • Zahlungsportale vom Typ Shop rechnen nach einem Ereignis ab, zum Beispiel einem Kauf in Ihrem Onlineshop.
  • Zahlungsportale vom Typ Zugang rechnen zeitbasiert ab, zum Beispiel monatliche Gebühren für ein Abonnement oder eine Video-Flatrate.

---end

Um ein Zahlungsportal des Typs Shop zu erstellen, muss lediglich nach der Namensvergabe noch die Shop-URL im Format http://www.ihreURL.de angegeben werden. Abhängig von den gebuchten Optionen ist eine Absenderadresse für durch PAYONE zu versendende E-Mails an Endkunden einzutragen. Zusätzlich sind hier durch den PAYONE Merchant Service nach Buchung die verwendeten Schnittstellen aktiviert.

Bei einem Zahlungsportal des Types Zugang muss mindestens ein Angebot erstellt werden, welches evtl. noch nicht angelegt wurde.

Die Anzahl der Shops bzw. Zugänge wird von PAYONE festgelegt. Nehmen Sie gerne mit uns Kontakt auf.

---end

Allgemein 
Für eine erfolgreiche Transaktion sollten die ersten drei Zeilen ausgefüllt sein..
Additional Response-Data

Sie haben zudem weitere folgende Konfigurationsmöglichkeiten für Nachrichten von der PAYONE Plattform an Ihr System:
Erweiterte Response-Daten -> Empfohlen: Einschalten

Hier können Sie für den Live- und Test-Modus getrennt einstellen, ob die API-Response zusätzliche Antwortparameter schickt..

  • Ausschalten: es werden lediglich „status“, „txid“, und „userid“ in der Antwort geschickt..
  • Einschalten: es werden zusätzlich Daten wie Mandats-Informationen und weitere Informationen zur Zahlungsart (abhängig von der Zahlungsart) geschickt.
Transaktions-Status
Transaktionsstatus -> Empfohlen: alles aktivieren

Hier können Sie den Inhalt des Transaktionsstatus definieren (für Live- und Test-Modus einheitlich).
Notify-Version

Notify-Version -> Standard / Empfohlen: Notify Version 7.6

Relevant zurzeit für folgende Zahlungsarten: Paydirekt (PDT), PayPal (PPE), Amazon Pay (AMZ)

Version 7.6, empfohlene Einstellung für Neu-Integrationen: Neuer Parameter „transaction_status“ wurde eingeführt mit Werten „completed“ || „pending“ für "txaction=capture". Außerdem neuer Parameter „reasoncode“ für „transaction_status=pending“

Weitere Hinweise finden Sie in der Server-API-Dokumentation im Kapitel „Parameter for the TransactionStatus query“

Weitere Hinweise finden Sie in der Server-API-Dokumentation im Kapitel Parameters for the TransactionStatus query .
TransactionStatus Failed
TransactionStatus Failed -> Empfohlene Einstellung für Neu-Integrationen: Melden
  • Melden: Es wird ein Transaktionsstatus für fehlgeschlagene Transaktionen verschickt (ab Notify-Version 7.5).
  • Nicht melden: Es wird ein Transaktionsstatus für fehlgeschlagene Transaktionen unterdrückt.

---end

Erweitert

Anschließend ist die Konfiguration im nächsten Reiter [Erweitert] fortzusetzen. Hier sollte die Trans­ak­tionsstatus-URL eingetragen werden, die Adresse, an die PAYONE Ihnen Statusänderungen aller Zahlungsvorgänge und weitere zahlungsrelevante Informationen per HTTP-Request übergeben soll.
Sie muss im Format http(s)://www.ihreURL.de angegeben werden. Außerdem wählen Sie hier den Key (siehe Info-Box).

Was ist der Key?

Um sicher zu stellen, dass nur Sie als Händler mit unserer Plattform in Kontakt treten, wählen Sie einen Key. Diese persönliche Identifikation ist nur Ihnen bekannt und wird bei jedem Aufruf einer PAYONE Schnittstelle als MD5-Hashwert (in Kleinbuchstaben) übergeben.

Sie können den Key frei wählen, erforderlich ist ein Key mit mindestens 16 zufällig gewählten Zeichen (Klein- und Großbuchstaben, Sonderzeichen, Zahlen, keine Umlaute, maximal 150 Zeichen). Bspw.: vX80Tevkx#3Gp86g%w9!

Wir empfehlen einen Key mit min. 30 Zeichen.

Geben Sie diesen Key niemals an Dritte weiter!

Der Key muss zwingend mit den Daten übereinstimmen, die in Ihrem Shop-System hinterlegten wurden!

---end

---end

Im PMI können eine Reihe genereller Vorgaben gemacht werden, die aber individuell mit Parametern des jeweiligen API-Requests überschrieben werden können. Generell gilt: Ein API-Request wird höher bewertet als Einstellungen im PMI. Details hierzu finden Sie in der API-Dokumentation. Überschreibbare erweiterte Einstellungen sind:

  • Die Zurück-URL, auf die ein Käufer bei einer nicht erfolgreichen Transaktion weitergeleitet wird, zum Beispiel wenn er sich nach einer Weiterleitung (bspw. zu PayPal) für einen Kaufabbruch entscheidet
  • Die Erfolgs-URL, auf die ein Käufer entsprechend bei erfolgreichem Abschluss der Bestellung weiter­ge­leitet wird.
  • Der Verwendungszweck, der z.B. bei Lastschrift- oder Kreditkartenzahlungen dem Käufer auf seinem Konto­auszug bzw. seiner Kreditkartenabrechnung angezeigt wird. Priorisiert wird das, was im Shop hinterlegt ist. Ansonsten, wird das ausgegeben, was im Verwendungszweck hinterlegt ist bzw. falls nichts eingeben wurde, und nichts im Shop hinterlegt ist, wird die URL ausgegeben.

Empfohlen: "md5 oder sha2"

Diese Einstellung stellt einen Kompromiss aus Kompatibilität für ältere Applikationen und Sicherheit dar. Für größtmögliche Sicherheit empfehlen wir, alle Applikationen auf die Nutzung des sha2-384 Verfahrens umzustellen.

Das letzte Feld dient dem Hinzufügen von Templates für Benutzer der Frontend-Schnittstelle. Hier können Standardvorlagen für das Aussehen der Benutzeroberfläche eingefügt werden, die zusätzlich in einem er­weiterten Dialog individualisiert werden können. So fügen sich die Felder nahtlos in das Design Ihres Onlineangebots ein, PAYONE tritt infolgedessen in Ihrem Checkout-Prozess nicht in Erscheinung.

Optionen

Der Reiter [Optionen] wird bei der Anlegung Ihres Accounts bereits von uns vorbelegt und kann in teilen von Ihnen bearbeitet werden.

API-Parameter

Der Reiter [API-Parameter] enthält eine zusammenfassende Übersicht der absolut notwendigen Daten in der Kommunikation zu Ihrem Shop-System, sowie eine Auflistung der von Ihnen angelegten Sub-Accounts (nächster Abschnitt: Erstellung von Sub-Accounts).

Für eine erfolgreiche Transaktion sollten alle Felder ausgefüllt sein und zudem mit den im Shop-System hinterlegten Daten übereinstimmen.
Riskcheck

Der Reiter [Riskcheck] steht Ihnen nur zu Verfügung, wenn Sie das Produkt Risikomanagement beauftragt haben.

Bitte informieren Sie sich hier ausführlich zu den verschiedenen Riskcheck-Verfahren und stellen Sie sicher, dass Ihre Konfiguration mit Ihren Anforderungen/Wünschen übereinstimmt.

---end

Erstellung von Sub-Accounts

Sub-Accounts dienen rein analytischen Zwecken und können nach Ihren eigenen Vorstellungen angelegt werden. Es können beliebig viele Sub-Accounts verwendet werden, mindestens einer muss aber erstellt werden.

Anwendungsbeispiele für Sub-Accounts

Betreiben Sie Ihr Onlineangebot in mehreren Staaten, so bieten Ihnen Sub-Accounts ein komfortables Werkzeug zur Aufschlüsselung der länderspezifischen Umsätze. Auch die Analyse des Umsatzes aus verschiedenen Leadquellen kann bequem über Sub-Accounts erfasst werden. Weitere Beispiele wären Rabattaktionen, filtern nach Artikelgruppen oder auch die Aufteilung in Sommer- und Wintermonaten.

Die konkrete Anwendung findet über den Parameter aid statt, welcher im Rahmen der jeweiligen Requests (siehe API-Dokus: Server API, Frontend, Client API ) übermittelt wird.

---end

Standardmäßig existiert noch kein Sub-Account.

Diesen erstellen Sie über Konfiguration >> Accounts. Ein Klick auf Account erstellen speichert Ihren neuen Sub-Account.

Der Name des Sub-Accounts muss payoneweit eindeutig sein, da Sie andernfalls eine Fehler­meldung erhalten.

---end

---end

Die wichtigsten Account-Daten auf einem Blick

Nutzen Sie die PAYONE Plattform über eine Extension, zum Beispiel für Magento, OXID oder pixi*? 
Dann müssen Sie in Ihrem Modul noch Daten wie die Portal-ID etc. eingeben. Diese und weitere notwendige Daten finden Sie unter:

API-Parameter

Auch bei der Anbindung der verschiedenen Schnittstellen benötigen Sie diese Daten.

Die Grundkonfiguration Ihres Merchant-Accounts ist damit abgeschlossen.

Nun können Sie abhängig von den verwendeten Schnittstellen auf verschiedenen Wegen Zahlungstransaktionen über die PAYONE Plattform abwickeln.

---end

Kommunikation mit der Plattform über Schnittstellen

Die Schnittstellen unterscheiden sich wesentlich in Ihren Funktionen, eine vollständige Beschreibung finden Sie in der Leistungsbeschreibung der PAYONE Plattform. Hier ein kurzer Überblick:

Beschreibung Server API Client API Frontend
Stark vereinfachte PCI DSS-Zertifizierung für Händler         
Reservierung         
Kauf         
Einzug von Zahlungen         
Gutschrift buchen         
Forderung buchen         
Aktualisierung von Kundendaten         
Steuerung des Mahn­wesens         

---end

PCI DSS: 
Sicherheit für Kreditkartendaten

Der Payment Card Industry Data Security Standard (PCI DSS) ist ein Regelwerk zum Umgang mit Kreditkartendaten. Unternehmen, die Kreditkartendaten verarbeiten oder speichern, müssen sich zertifizieren lassen. Mit der Client API und Frontend jedoch können Sie als Händler die Zerti­fizierung stark vereinfachen, denn die sensiblen Daten werden direkt an die PAYONE Plattform weitergeleitet und verarbeitet. PAYONE selbst ist nach dem höchsten Level 1 PCI DSS zertifiziert. Weitere Informationen dazu erhalten Sie direkt auf unserer Webseite.

---end

Ansprache der Plattform am Beispiel der Client/Server API

Jeder Zahlungsvorgang lässt sich als Aneinanderreihung einzelner Prozessschritte darstellen – in sogenannten Sequenzdiagrammen.

Anhand von zwei Beispielen werden nun häufige Geschäfts­vorfälle in einem Onlineangebot vom Kauf bis zur Auslieferung der Ware vorgestellt. Die Befehle und die Reihenfolge unterscheiden sich hier je nach genutzter Anbindung.

Details zu der von Ihnen genutzten Schnittstelle finden Sie in den technischen Referenzdokumenten (API-Dokus).

Vielfältige Lösungen:

Die PAYONE Plattform unterstützt zahl­reiche Zahlarten und Optionen, passend für Ihr Geschäftsmodell. Informieren Sie sich über die Möglichkeiten in der Leistungs­beschreibung der PAYONE Plattform oder kontaktieren Sie uns.

---end

Sequenzdiagramm einer Kreditkartenzahlung mit Vorautorisierung

Beispielhaft erklären wir den Ablauf einer Kreditkartenzahlung mit Reservierung und Einzug.

Dieser typische Ablauf empfiehlt sich, wenn vor Belastung der Kreditkarte zunächst noch die Verfügbarkeit der Ware geprüft werden soll, man aber sicherstellen möchte, dass der Betrag bei der nachfolgenden Abbuchung verfügbar ist. Häufig wird das vorherige Reservieren eines Betrages auch von Acquiringpartnern vorausgesetzt.

---end

1

Nach der Bestellung des Käufers werden dessen Kreditkartendaten bspw. über einen AJAX Call an die Client API übermittelt. Der Request hierfür lautet creditcardcheck, welcher die jeweilige Kreditkarte in Echtzeit auf Plausibilität prüft. Zusätzlich bietet dieser Request die Möglichkeit, Kartendaten (Kartennummer, Ablauf­datum) bei der PAYONE Plattform zu speichern. In diesem Fall liefert der Response eine so genannte Pseudokartennummer (pseudocardpan) zurück, die beim Händler gespeichert und durch die PAYONE Plattform wieder der realen Kreditkarte zugeordnet werden kann. So muss der Händler sich nicht nach PCI DSS zerti­fizieren lassen (siehe oben).

---end

2

Den nächsten Schritt stellt der Request preauthorization dar, der eine Reservierung der Bestellsumme beim Acquirer, also Ihrem Kreditkartenakzeptanzgeber, auslöst. Das Limit der Kreditkarte des Käufers wird hierbei entsprechend reduziert. Als weitere Parameter dieses Requests können z.B. die Kundennummer des Käufers und dessen Lieferadresse übergeben werden, wobei die konkrete Ausgestaltung des Requests variabel Ihren Ansprüchen folgend festgelegt werden kann. Die erfolgreiche Übermittlung wird mittels des Status approved bestätigt.

---end

3

Es folgt die Übermittlung des sogenannten TransactionStatus von der PAYONE Plattform in Form der Meldung appointed. Hierdurch wird die erfolgreiche Initiierung des Zahlungsvorgangs gemeldet. Die Zahlung ist nun vorgemerkt und der Bezahlvorgang für den Käufer beendet.

---end

4

Ist die bestellte Ware verfügbar und der Versand an den Käufer wurde initiiert, so können Sie im nächsten Schritt über den Request capture die zuvor reservierte Summe von der Kreditkarte des Käufers abbuchen. 

---end

5

Die erfolgreiche Übermittlung des Requests wird wiederum mit approved bestätigt und der anschließende Geldeinzug wird von PAYONE durch den TransactionStatus capture übermittelt. Abschließend folgt die Auszahlung von Kreditkartenzahlungen an Sie über Ihren Acquirer.

---end

Sequenzdiagramm einer Online-Überweisung

---end

1

Auch bei Nutzung einer Online-Überweisung folgt auf die Bestellung des Kunden der Request preauthoriza­tion. Übergeben werden hierbei neben den evtl. notwendigen Adressdaten zum Beispiel die Kontonummer und Bankleitzahl des Käufers, die auch in Ihrem Checkout abzufragen sind, da parallel zur Initialisierung einer Online-Überweisungssession eine Überprüfung der Kontodaten des Käufers stattfindet. Ferner werden die Kontodaten für etwaige Gutschriften nach Retouren gespeichert.

---end

2

Dem Response redirect folgt die Weiterleitung des Käufers zu seiner Bank. Dieser loggt sich über die ihm bekannte Oberfläche mit seinen Kontodaten ein und bestätigt daraufhin die gewünschte Zahlung.

---end

3

Die Käuferbank informiert infolgedessen PAYONE über den Zahlungserfolg und das Käuferkonto wird (im Gegensatz zur Vorautorisierung bei einer Kreditkarte) sofort belastet. Die PAYONE Plattform übermittelt daraufhin den TransactionStatus appointed, der die erfolgreiche Zahlung bestätigt. Der Käufer wird abschließend auf die Erfolgs-URL Ihrer Webseite zurückgeleitet.

---end

4

Dem im nächsten Schritt durchgeführten Versand der Ware folgt in Form des Requests capture die Verbuchung der Forderung. 

---end

5

Der Response approved bestätigt auch hier die erfolgreiche Übermittlung des Requests und wird im Anschluss durch TransactionStatus capture formal abgeschlossen. Die Überweisung erfolgt direkt auf das von Ihnen im Aufschaltprozess bei PAYONE angegebene Konto.

---end

Transaktionslogs: Hilfe zur Fehleranalyse 

Ihre Transaktion wurde nicht erfolgreich beendet? Ein offener Transaktionsstatus kann auf eine Reihe von Gründen zurückzuführen sein. Einen ersten Anhaltspunkt finden Sie im PAYONE Merchant Interface (PMI). Suchen Sie unter Debitorenverwaltung die Transaktion anhand der PAYONE Vorgangsnummer (TX-ID) und klicken auf Details zum Zahlungsvorgang: Hier findet sich das Feld Fehlergrund. Sollte der Hinweis dort nicht zur Klärung ausreichen, können Sie unter [Konfiguration] >> [Transaktionsstatus] alle aktuell blockierten Trans­aktionen einsehen und weitere Details zum Fehlergrund aufrufen, sofern diese nicht älter als 48 Stunden sind und die maximale Versuchsanzahl von 12 noch nicht überschritten wurde.

Zugangsberechtigungen

Sollten Sie weitere Zugänge benötigen, ist es innerhalb der PMI mit entsprechenden Benutzerrechten jederzeit möglich, bestehende Zugänge zu verwalten und neue Zugänge zu erstellen. So können zum Beispiel mehrere Mitarbeiter im Kundendienst, die Buchhaltung, Technik oder ggf. externe Dienstleister wie Agenturen mit personalisierten Zugängen ausgestattet werden. Jedem Zugang können individuelle Berechtigungen für Sub-Accounts (siehe unten) sowie entsprechende Lese- oder Schreibrechte zugewiesen werden.