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:
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 Verwaltungsoberfläche der PAYONE Plattform.
---end
Sie haben einen Testzugang erhalten und wollen das Setup unverbindlich ausprobieren.
---end
Schritt für Schritt zur ersten Transaktion
Wenn Sie Requests im Live-Betrieb durchführen, so werden diese bei Ausführung auch extern weitergeleitet – 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.
---end
---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 Debitorenmanagement 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.
---end
Allgemein
---end
Erweitert
Anschließend ist die Konfiguration im nächsten Reiter [Erweitert] fortzusetzen. Hier sollte die Transaktionsstatus-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!
---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 weitergeleitet wird.
- Der Verwendungszweck, der z.B. bei Lastschrift- oder Kreditkartenzahlungen dem Käufer auf seinem Kontoauszug 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.
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 erweiterten 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.
---end
Erstellung von Sub-Accounts
Sub-Accounts dienen rein analytischen Zwecken und können nach Ihren eigenen Vorstellungen angelegt werden. Mindestens einer muss erstellt werden. Die Anzahl der Unterkonten ist auf 100 Sub-accounts begrenzt.
Sollten Sie mehr Unterkonten benötigen, kontaktieren Sie bitte unseren Kundensupport.
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.
---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 Mahnwesens |
---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 Zertifizierung 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äftsvorfä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 zahlreiche Zahlarten und Optionen, passend für Ihr Geschäftsmodell. Informieren Sie sich über die Möglichkeiten in der Leistungsbeschreibung 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.
---end
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, Ablaufdatum) 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 zertifizieren lassen (siehe oben).
---end
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
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
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
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
Auch bei Nutzung einer Online-Überweisung folgt auf die Bestellung des Kunden der Request preauthorization. Ü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
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
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
Dem im nächsten Schritt durchgeführten Versand der Ware folgt in Form des Requests capture die Verbuchung der Forderung.
---end
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 Transaktionen 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.
