Zahlungsabwicklung

Zahlung über den Payment Provider

Einleitung:

Sie bestimmen das Angebot und den Preis für Ihre Produkte / Dienste. Der Kunde wählt in Ihrem Iframe ein Produkt. Um den Bezahlvorgang anzustoßen, rufen Sie eine Lightbox mit dem onOffice Zahlungsdialog auf. Hier lässt sich onOffice die Bestellung vom Benutzer bestätigen.

Die möglichen Zahlungsarten sind Kreditkarte und SEPA-Lastschrift. Es können mehrere Kreditkarten bzw. Bankverbindungen pro Konto hinterlegt sein. Der Kunde wählt beim Kauf die passende Zahlungsart. Für die Zahlungsübermittlung arbeiten wir mit dem Payment-Provider Mangopay zusammen.

Jeder Marketplace-Partner schliesst einen gesonderten Vertrag mit Mangopay und erhält dort ein Konto, welches wir für Sie einrichten. Die Einnahmen können dann über einen Pay-Out auf das eigene Konto übertragen werden. In Ihrer Transaktionsübersicht unter dem Menüpunkt Marketplace >> Anbieterkonto können Sie alle getätigten Transaktionen einsehen.

Sandbox- und  Production-Modus :

Es gibt grundsätzlich 2 verschiedene Modi, in denen der Marketplace läuft. Der Sandbox-Modus dient zum Testen Ihres Shop in der Entwicklungsphase und alle Transaktionen werden ohne Echtgeld mit Testkreditkarten durchgeführt.

Im Production-Modus werden alle Transaktionen mit Echtgeld durchgeführt. Wenn Ihr Shop fertigprogrammiert und durchgetestet ist, kann Ihr Shop auf den Production-Modus umgestellt werden.

Geben uns Bescheid, wenn wir Ihren Shop umstellen sollen. Wir bei onOffice testen dann noch die Schnittstellen Ihres Shops zu onOffice enterprise und tauschen Ihre Wallet-Id aus.

Um spätere Erweiterungen Ihres Shop weiterhin testen zu können, können wir Ihnen gerne einen zweiten Testanbieter für Testzwecke einrichten, der im Sandbox-Modus läuft. Sprechen Sie uns dazu bitte an, falls Sie einen Testanbieter im Sandbox-Modus benötigen. Bitte nennen Sie uns dazu die Freischalt- und Service-URL sowie MangoPay-Walletid ihres Testservices. Alle weiteren Informationen sind die gleichen wie bei Ihrem echten Anbieter.

Oben rechts in der Menüleiste in enterprise wird der Status als „Sandbox“ oder „Production“ in Ihrem Anbieter-Mandant angezeigt. Wenn dort weder „Sandbox“ noch „Production“ steht, dann ist Ihr Anbieter nicht (korrekt) verknüpft. Melden Sie sich in diesem Fall bei uns. Auf keinen Fall sollen Sie irgendwelche Konten anlegen.

Testkreditkarten:

Um die Zahlungsabwicklung testen zu können, bietet Mangopay Testkarten an, um Transaktionen zu simulieren. Durch die Umstellung auf 3DSV2-Secure können nur noch die 2 3DSV2-Testkarten mit „frictionless flow“ und „challenge flow“ verwendet werden. Zum Testen eignet sich eher der „frictionless flow“, da hier meist keine 3DSV2-Eingabe nötig sein sollte, allerdings können auch keine größeren Beträge gebucht werden.

Alternativ kann man die Karten unter „liability shift“ mit dem auf der Seite genannten Passwort nutzen, wo allerdings immer eine 3DSV2-Sicherheitsabfrage erfolgt.

KYC-Dokumente für MangoPay:

Die EU-Anti-Geldwäsche-Richtlinie erfordert eine Legitimationsprüfung in Form von KYC-Dokumenten (Know your customer), daher bitten wir Sie uns folgende Dokumente zur Verfügung zu stellen:

• IDENTITY PROOF -> Reisepass, Personalausweis oder Führerschein
• REGISTRATION PROOF -> Handelsregisterauszug
• ARTICLES OF ASSOCIATION -> Gesellschaftsvertrag
• SHAREHOLDER DECLARATION -> Liste der Gesellschafter (https://www.mangopay.com/terms/shareholder-declaration/Shareholder_Declaration-EN.pdf)

Transaktionsliste: Pay-Out und Stornieren von Transaktionen

Unter dem Menüpunkt Marketplace >> Anbieterkonto können Sie alle Transaktionen einsehen, die Ihre Kunden bei Ihnen getätigt haben.

• Filterleiste: Im oberen Bereich können Sie über die Filterleiste die angezeigten Transaktionen der Transaktionliste steuern. Sie können nach Datumsbereichen, der Transaktions-ID oder nach weiteren Kriterien in „Weiterer Filter 1:“ filtern. Als Datumsbezug kann der Buchungstag oder der Zeitpunkt der Wertstellung gewählt werden. SEPA-Transaktionen z.B. können einige Tage brauchen, bis sie durchgeführt sind.
• Buchung stornieren: Transaktionen können storniert werden in Ihrer Transaktionsübersicht über das Icon für „Buchung stornieren“.  Dabei wird die Rückzahlung des Transfers über die Mangopay-API angestoßen. Die stornierte Transaktion wird in der Transaktionsübersicht als Transaktion mit negativem Betrag dargestellt. Der Käufer erhält eine E-Mail über die Stornierung der Transaktion. Es können keine Transaktionen älter als 11 Monate storniert werden. Eine Stornierung ist erst möglich, wenn der Status der Transaktion auf erfolgreich steht. D.h. bei Transaktionen mit Zahlungsart SEPA, die „in Bearbeitung“ sind, ist eine Stornierung nicht möglich. Eine Stornierung ist auch per API mit dem API-Call Transaktion stornieren möglich. Für den Fall, dass das Wallet nicht ausreichend gedeckt ist, kommt die Rückmeldung: “Dieses Mangopay-Konto ist nicht ausreichend gedeckt. Die Stornierung konnte nicht durchgeführt werden.” Daher empfehlen wir einen kleinen Betrag auf den Konten zurückzulassen, für den Fall, dass es zu Stornierungen kommt. Sonst kann es zu Problemen kommen, wenn bei einem nicht gedeckten Konto storniert wird. Beachten Sie, dass momentan beim Payout nur der gesamte Betrag transferiert werden kann.
• Abonnements kündigen: Über das Sanduhr-Icon können Sie Abonnements kündigen.
• Nachzahlungslink generieren: Über das Euro-Icon können Sie einen Nachzahlungslink generieren und an Ihre Kunden versenden.
• Details zu der Transaktion:  Über das Lupen-Icon können Sie weitere Details zu der Transaktion einsehen. Hier sind weitere wichtige Informationen wie die Zahlungsart (Kreditkarte oder Bankkonto), die Rechnungsadresse des Käufers sowie detaillierte Informationen zur Bestellung zu finden.
• Status einer Transaktion: In der Spalte Status ist der Status der Transaktion zu sehen. Mögliche Werte sind: erfolgreich, fehlgeschlagen oder in Bearbeitung. Der Status „in Bearbeitung“ wird immer und nur bei der Zahlungsart SEPA gesetzt. In diesem Fall hat der Zahlungsanbieter die Abbuchung bei der Bank beantragt. Das Geld wird erst nach einigen Tagen vom Kunden eingezogen. Am Folgetag wird der Status dann auf erfolgreich umgesetzt, wenn die Zahlung geklappt hat. Im Prinzip kann man also erstmal den Status „in Vorbereitung“ so behandeln wie „erfolgreich“.  Sollte eine Zahlung fehlschlagen, werden Sie per Mail davon unterrichtet und die Zahlung steht auf fehlgeschlagen. Das Geld muss dann per Nachzahlungslink nachgefordert werden.
• Referenz-ID: Über das Feld „Referenz-ID“ können Ihre Kunden eine Abbuchung von Mangopay auf ihrem Bankkonto einer bezahlten Marketplace-Dienstleistung zuordnen. Die Referenz-ID wird der Bank als Referenznummer mitgeteilt und erscheint auf dem Kontoauszug. Die Referenz-IDs sind für jeden Kunden eindeutig.
• Kontostand: Der aktuelle Kontostand Ihres Mangopay-Wallets wird hier angezeigt.
• Payout: Über „Auszahlung ausführen“ können Sie den gesamten Betrag Ihres Mangopay-Kontos auf das von Ihnen hinterlegte Bankkonto überweisen. Es folgt eine Sicherheitsabfrage: “Möchten Sie eine Auszahlung veranlassen? Der komplette Betrag auf Ihrem Mangopay Konto (XXX,XX€ ) wird auf das Konto mit der IBAN ***0147 überwiesen. Achtung. Stornierungen sind danach erst wieder möglich, wenn das Konto ausreichend gedeckt ist.” Der Verwendungszweck der Überweisung lautet „Marketplace“. In der Transaktionsliste wird die Auszahlung als Transaktion vom Typ „Auszahlung“ dargestellt. Auszahlung von Teilbeträgen ist momentan nicht möglich.
• CSV-Export: Über die Links „akueller Monat“ und „letzer Monat“ bei „CSV-Export“  können die Transaktionen des aktuellen und letzten Monats als CSV-Datei heruntergeladen werden. Über „Gefilterte Liste“ wird die aktuelle, gefilterte Auswahl in der Transaktionsliste exportiert.

Ablauf einer Transaktion:

Am Beispiel der Grundriss-Optimierung stellt sich der Ablauf einer Transaktion wie folgt dar (in kursiv):

1. Der Kunde wählt in Ihrem Iframe das Produkt aus.
   Bsp.: Der Kunde entscheidet sich für den Grundriss-Typen B zum Preis von 14,90€.
2. Der Anbieter ruft den Zahlungsdialog von onOffice auf und übermittelt dabei die Bezeichnung, den Preis und die Anzahl für das ausgewählte Produkt.
   Bsp.: Der Grundrissanbieter ruft den onOffice Zahlungsdialog auf und übermittelt die Bezeichnung für das vom Kunden ausgewählte Produkt (z. B. Grundriss-Typ B), den Preis (z. B. 14,95€) sowie die Anzahl.
   

   Lightbox Marketplace Bestellung

3. Der Kunde bestätigt den Kauf. Möglicherweise wird der Kunde bei manchen Käufen auf eine 3D-Secure-Seite seiner Bank / seines Kreditkartenunternehmens weitergeleitet, wo er sich mit einem Sicherheitscode authentifizieren muss. Daraufhin stößt onOffice den Bezahlvorgang beim Payment Provider an. Dieser zieht die Summe beim Kunden ein und transferiert sie auf Ihr Konto.
   Bsp.: Der Kunde bestätigt den Kauf vom Grundriss-Typ B zum Preis von 14,95€. Die Summe wird auf Ihr Konto übertragen.
4. onOffice sendet die Information darüber, ob der Kauf bestätigt wurde oder es ein Problem gab. War der Kauf erfolgreich, erhält der Kunde eine Auftragsbestätigung per E-Mail.

Marketplace in anderen Ländern / Mehrwertsteuer:

Der Marketplace wird in Zukunft nach und nach in weiteren Ländern ausser Deutschland, Schweiz und Österreich verfügbar gemacht. Seit Kurzem ist der Marketplace auch in Italien, Spanien und Slowenien gestartet, in der Anfangsphase sind evtl. noch wenige Anbieter für die neuen Länder verfügbar. Im Bestell-Popup wird die Mehrwertsteuer wie folgt berücksichtigt:

• wenn es sich um einen deutschen Kunden handelt, wird die Mehrwertsteuer immer berechnet.
• wenn es sich um ein EU-Land handelt, wird bei einer eingetragenen Umsatzsteuer-ID keine Mehrwertsteuer berechnet.
• wenn keine Umsatzsteuer-ID für ein EU-Land eingetragen ist, wird die Mehrwertsteuer berechnet.
• es wird keine Mehrwertsteuer berechnet, wenn es sich um ein Drittland (nicht-europäisches Ausland) handelt.

Aufbau des Links zur Zahlungsabwicklung

Nachdem der Kunde aus dem Anbieter-Iframe heraus eine Bestellung getätigt hat, öffnet sich die Lightbox für die Zahlung.

Der im Iframe aufgerufene Dienst muss die Daten dafür als JSON String per postMessage an das Parent-Fenster übergeben. Der JSON String muss mit dem Secret des Anbieters signiert werden, somit kann die Anfrage authentifiziert werden.

Der JSON sollte folgenden Aufbau haben:

Bitte beachten Sie: Momentan kann nur jeweils ein Produkt pro Bestellung angeboten werden. Bitte beachten Sie: SEPA-Zahlungen werden anders behandelt und haben einen eigenen Status „inprocess“. Mehr dazu in der Erläuterung des Parameter „status“.

Erläuterung der Parameter

• “callbackurl”: Diese URL wird nach einer Zahlung aufgerufen und liefert mehrere Parameter per Querystring (plus evtl. individuelle Parameter):
  • “transactionid”: Eine eindeutige ID der spezifischen Transaktion. Diese soll von Ihnen gespeichert werden für spätere Verarbeitungszwecke sowie zur Nachverfolgbarkeit
  • “referenceid” : Diese Referenz-ID erscheint bei Bank-Überweisungen auf dem Überweisungsträger als Kunden-Referenznummer, damit der Kunde die Transaktion zuordnen kann.
  • “status”: Liefert entweder “success”, “inprocess“ oder “error”. Der Status „inprocess“ wird nur für die Zahlungsart SEPA-Lastschrift verwendet, da dort die Abwicklung der Transaktion mehrere Tage dauern kann. D.h. bei „inprocess“ handelt es sich immer um eine SEPA-Transaktion. In dem Fall hat der Zahlungsanbieter die Abbuchung bei der Bank beantragt. Das Geld wird erst nach einigen Tagen vom Kunden eingezogen. Am Folgetag wird der Status dann auf „success“ umgesetzt, wenn die Zahlung geklappt hat. Im Prinzip kann man erstmal den Status „inprocess“ so behandeln wie den Status „success“. Sollte eine Zahlung fehlschlagen, werden Sie per Mail davon unterrichtet und die Zahlung steht auf fehlgeschlagen. Das Geld muss dann per Nachzahlungslink nachgefordert werden.
  • “errorCodes”: Liefert einen Errorcode, sofern ein “error” zurückgegeben wurde. (Errorcodes und -beschreibungen siehe Errorcodes.)
  • “message”: Liefert die Beschreibung des Errorcodes, sofern ein “error” zurückgegeben wurde.
  • “timestamp”
  • “signature”

  Weitere individuelle Parameter (z.B. Produkt-ID), die für Ihre Verarbeitung notwendig sein könnten, können von Ihnen frei festgelegt werden. Auch beim Callback sollte die Callback-URL auf die Signatur geprüft werden.

• “parametercacheid”: Wird dem Anbieter beim Service als Querystring Parameter übergeben und muss hier wieder zurückgeliefert werden. Der Parameter enthält interne Informationen, die im Parameter-Cache gespeichert werden.
• “products”: Hier müssen die vom Benutzer ausgewählten Produkte aufgeführt werden mit “name”, “price” und “quantity”. “circleofusers” ist optional und bestimmt den Benutzerkreis, für den gekauft wurde. Mögliche Werte: Mandant (customer), Bürogruppe (group), Benutzer (user). Wichtig ist, dass der Preis immer mit einem Punkt “.” als Nachkommastellentrenner geliefert wird. Außerdem dürfen keine anderen Trennzeichen wie Tausendertrennzeichen genutzt werden, und der Preis als wird Netto-Preis geliefert wird. Außerdem sollten alle Preise immer mit zwei Nachkommastellen angegeben werden. Bitte beachten Sie: Momentan kann nur jeweils ein Produkt pro Bestellung angeboten werden.
• “timestamp”: Hier soll ein timestamp generiert werden, der in die Signatur einfließt und sie somit eindeutig macht.
• “totalprice”: Dies ist der Gesamtpreis über alle Produkte. (Hier gelten die gleichen Regeln wie bei den Produktpreisen)
• “signature”: Diese muss über den JSON String gebildet werden, damit die Gültigkeit validiert werden kann. (siehe Erläuterung zur Signatur)

In den Code-Beispielen finden Sie einen Beispielshop mit der Implementierung der Signatur-Generierung. Bitte beachten Sie, dass der Demoshop keine Validierung der URL  bzw. der Signatur durchführt, sodass dies von Ihnen implementiert werden muss.

Errorcodes

Falls bei der Bestellung ein Fehler unterläuft und als “status” ein “error” zurückgegeben wird, können folgende Errorcodes als “errorCodes” erscheinen.

Mögliche Fehler:

• 1000 Ein unbekannter Fehler ist aufgetreten
• 1001 Json-string konnte nicht gelesen werden
• 1002 Signatur war nicht korrekt

• 1011 Ein Preis hatte nicht die korrekte Formatierung. Erwartet ist ein Preis mit zwei Nachkommastellen mit Dezimalpunkt (z.B. 15.23)
• 1012 Gesamtpreis ist nicht korrekt. Der Gesamtpreis muss mit dem Preis im Produkt oder der monatlichen Abo-Zahlung übereinstimmen.
• 1013 Datenstruktur nicht korrekt. Es muss entweder genau ein Produkt-Datensatz oder genau ein Abo-Datensatz übergeben werden.

• 1021 Parameter timestamp fehlt.
• 1022 Parameter signature fehlt.
• 1023 Parameter parametercacheid fehlt.

• 1031 Transaktion wurde bereits ausgeführt (bei Nachzahlungen).
• 1032 Der eingeloggte User stimmt nicht mit der übermittelten userId überein.
• 1033 Der Kunde hat kein aktives Konto.

• 1101 MANGOPAY-Fehler: Kunde hat kein MANGOPAY Wallet.
• 1102 MANGOPAY-Fehler: Kunde hat kein Zahlungsmittel eingestellt.
• 1103 MANGOPAY-Fehler: Anbieter hat kein MANGOPAY-Wallet.
• 1104 MANGOPAY-Fehler: Zahlung kann wegen 3D Secure nicht durchgeführt werden.
• 1105 MANGOPAY-Fehler: Einzahlung auf das MANGOPAY-Wallet nicht möglich.
• 1106 MANGOPAY-Fehler: Transfer zum MANGOPAY-Wallet nicht möglich. Nicht genug Geld auf dem MANGOPAY-Wallet des Kunden.
• 1107 Unbekannter Fehler beim Zahlungsvorgang bei MANGOPAY.

• 8505 Die Begrenzung von zehn Zahlungen am Tag je Kreditkarte wurde überschritten.

In allen Fällen hat keine Zahlung stattgefunden, also sollten alle Fehler von Ihnen als Anbieter behandelt werden.

Erläuterung zur Signatur des JSON-Strings

Die Methode zur Signaturberechnung finden Sie in der CreateProductJsonOrderwithSignature.php der Demo-Shopwebseite. Der Ablauf der Signaturberechnung geschieht wie folgt:

• Aufruf der Funktion sign zum Signieren.
• Hinzufügen eines Timestamp.
• Sortieren der Parameter von A-Z: Zunächst werden alle Einträge entsprechend des Parameternamens sortiert.
• Erstellen der Signatur:
  • sha256 wird als Algorithmus genutzt.
  • Das Secret des Anbieters wird als Schlüssel genutzt.
  • Die JSON Daten werden per json_decode($jsonString, true) in ein array umgewandelt. Dies wird dann mit http_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986); zu einem String zusammengesetzt. Dieser String wird dann per hash_hmac(‘sha256’, $jsonQueryBuildString, $AnbieterSecret); signiert.
• Zum Abschluss wird die erhaltene Signatur im JSON Array angehängt und das Array dann wieder per json_encode($jsonArraywithSignature, JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_LINE_TERMINATORS) in einen JSON String umgewandelt.

Beispiel der Signaturberechnung mit Testdaten:

 // Rufe die Funktion sign($jsonData, $secret) in CreateProductJsonOrderwithSignature.php mit den Parametern JSON-Data und Secret auf:
$jsonData = '{"totalprice":"26.47","callbackurl":"https://www.anbietershop.de/HandleonOfficeOrderResponse.php","parametercacheid":"0e81f10f-6de8-4edc-cdcf-de96cf61624c","products":[{"quantity":"3","circleofusers":"customer","price":"5.99","name":"onOffice Sample 1"}]}'
$secret = 'myTestSecret'

// Füge timestamp hinzu (hier 1565689180);
$jsonDecodedContent['timestamp'] = time();

// Sortiertes Array nach Durchlaufen von $contentSorted = sortParameters($jsonDecodedContent):
[
  "callbackurl" => "https://www.providershop.de/MarketplaceDemoShop/ResultPage.php",
  "parametercacheid" => "84839588-cd83-53be-881b-3fa953a853e2",
  "products" => [
      [
        "circleofusers" => "customer"
        "name" => "Produktname"
        "price" => "0.08"
        "quantity" => "1"
     ],
   ],
  "timestamp" => "1565689180"
  "totalprice" => "0.08"
]

// Der zu signierende String sieht nach Aufruf von http_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986) dann folgendermaßen aus:

callbackurl=https%3A%2F%2Fwww.anbietershop.de%2FHandleonOfficeOrderResponse.php&parametercacheid=0e81f10f-6de8-4edc-cdcf-de96cf61624c&products%5B0%5D%5Bcircleofusers%5D=customer&products%5B0%5D%5Bname%5D=onOffice%20Sample%201&products%5B0%5D%5Bprice%5D=5.99&products%5B0%5D%5Bquantity%5D=3&timestamp=1565689180&totalprice=26.47

// Mit dem Secret "myTestSecret" wird über $jsonSignature = hash_hmac('sha256', $jsonQueryContent, $secret) folgende Signatur generiert:
451d116c62fe3b67a2409e38fcac35cc2ccacd9b5dd799c88c7293e32d61dc46