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. Bei der Anbieteraufnahme können Sie uns mitteilen, falls für Ihren Service die möglichen Zahlungsarten eingeschränkt werden sollen (z.B. Kunde soll nur per Kreditkarte zahlen können).
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.
D.h. Testkarten, die keine 3DSV2-Abfrage haben, funktionieren deshalb nicht. Die funktionierenden Testkarten sind momentan 4970105191923460 und 4970105181854329.
Alternativ kann man die Karten unter „liability shift“ mit dem auf der Seite genannten Passwort nutzen, wo allerdings immer eine 3DSV2-Sicherheitsabfrage erfolgt.
FR7630004000031234567890143 funktioniert für SEPA-Transaktionen. Falls die Testkreditkarten nicht funktionieren sollten, kann diese alternativ benutzt werden.
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. 
Fiilterleiste und Icons:
- 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.
Spalten:
- Buchungstag: Datum des Kaufes.
- Wertstellung: Datum der Wertstellung.
- Transaktions-ID: Transaktions-ID des Kaufes.
- 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.
- Mangopay-Konto-ID:
- Status: 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.
- Mandant: onOffice-Mandant, der den Kauf getätigt hat. Ein Mandant kann viele Benutzer haben.
- Käufer: onOffice-Benutzer, der den Kauf getätigt hat. Ein Benutzer gehört zu einem Mandanten.
- Preis: Preis des gekauften Produkts.
Kontostand, Auszahlung und Datenexport:
- Kontostand: Der aktuelle Kontostand Ihres Mangopay-Wallets wird hier angezeigt.
- Auszahlung: Ü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):
- 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€. - 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
- 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. - 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, Slowenien, Kroatien und Luxemburg gestartet, in der Anfangsphase sind evtl. noch wenige Anbieter für die neuen Länder verfügbar.
Ob und welche Mehrwertsteuer entrichtet werden muss, richtet sich nach der Rechnungsadresse des Käufers im Marketplacekonto und dem Land des Anbieters.
Im Bestell-Popup wird die Mehrwertsteuer wie folgt berücksichtigt:
- Rechnungsadresse hat das dasselbe Land wie der Anbieter und es ist eine USt.-ID eingetragen: MwSt. des Landes wird berechnet.
- Rechnungsadresse hat das dasselbe Land wie der Anbieter und es ist keine USt.-ID eingetragen: MwSt. des Landes wird berechnet.
- Rechnungsadresse ist abweichend vom Land des Anbieters und es ist keine USt.-ID eingetragen: MwSt. des Anbieterlandes wird berechnet.
- Rechnungsadresse ist abweichend vom Land des Anbieters und es ist eine USt.-ID eingetragen: Es wird keine MwSt. berechnet.
Die aktuell gültigen MwSt.-Sätze für die Länder, in denen der Marketplace verfügbar ist, lauten:
- Deutschland 19%
- Italien 22%
- Kroatien 25%
- Luxemburg 17%
- Österreich 20%
- Slowenien 22%
- Spanien 21%
Hinweis: Schweizer Kunden zahlen grundsätzlich keine Mehrwertsteuer.
Weitere Informationen zur USt.-ID finden Sie bei Wikipedia.
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:
{
"callbackurl": "https://www.anbietershop.de/HandleonOfficeOrderResponse.php",
"parametercacheid": "0e81f10f-6de8-4edc-cdcf-de96cf61624c",
"products": [
{
"name": "onOffice Sample 1",
"price": "5.99",
"quantity": "3",
"circleofusers": "customer"
}
],
"timestamp": 1565689180,
"totalprice": "26.47",
"signature": "649ee3dfbfb53187a9b2b66fafb658df24ca037c6de473fe9bcee2e327289dd5"
}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:
- Hinzufügen eines Timestamp.
- Parameter alphabetisch sortieren: die Parameternamen müssen in alphabetischer Reihenfolge sortiert werden. Die Parameternamen in Subarrays (wie z.B. products) müssen ebenfalls alphabetisch sortiert werden (rekursive Sortierung).
- Erstellen der Signatur:
sha256wird 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 mithttp_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986);zu einem String zusammengesetzt. Dieser String wird dann perhash_hmac(‘sha256’, $jsonQueryBuildString, $AnbieterSecret);signiert. Beachten Sie, dass dieser String, mit dem die Signatur berechnet wird, ein Hexadezimal-String sein und kleingeschrieben werden muss.
- 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.
Häufige Probleme bei der Signaturberechnung:
- Der Query-String, der signiert werden soll, wurde nach einem falschen RFC berechnet. Korrekt ist diesen nach RFC 3986 zu berechnen.
- Die Signatur wurde als base64-kodierter Binärstring berechnet, muss aber als Hexadezimal-Wert berechnet werden.
Beispiel der Signaturberechnung mit Testdaten:
Der Beispielcode kann hier als Textdatei runtergeladen werden. Für Testzwecke empfehlen wir damit zu arbeiten anstatt den Codeschnipsel hier von der Seite zu kopieren.
// Rufe die Funktion sign($jsonData, $secret) in CreateProductJsonOrderwithSignature.php mit den Parametern JSON-Data und
// und Secret auf:
$jsonData = '{"totalprice":"17.97","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 = json_decode($jsonData, true);
$jsonDecodedContent['timestamp'] = time();
// Sortiertes Array nach Durchlaufen von $contentSorted = sortParameters($jsonDecodedContent):
[
"callbackurl" => "https://www.anbietershop.de/HandleonOfficeOrderResponse.php",
"parametercacheid" => "0e81f10f-6de8-4edc-cdcf-de96cf61624c",
"products" => [
[
"circleofusers" => "customer",
"name" => "onOffice Sample 1",
"price" => "5.99",
"quantity" => "3"
]
],
"timestamp" => 1565689180,
"totalprice" => "17.97"
]
// 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¶metercacheid=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×tamp=1565689180&totalprice=17.97
// Mit dem Secret "myTestSecret" wird über $jsonSignature = hash_hmac('sha256', $jsonQueryContent, $secret)
// folgende Signatur generiert:
49b818db62d1b86640ea34f4525e64809fa44d5e0b90ad719aadd5425f66c9ba
Abonnements
Im Marketplace können auch Abonnements für Produkte oder Dienstleistungen angeboten werden, die monatlich abgerechnet werden. Das Abonnement startet direkt nach dem Kauf. Dann wird auch die erste Rate für das Abonnement abgerechnet. Es werden Abo-ID und Transaktions-ID übergeben.
Der JSON-Übergabeparameter für ein Abonnement wird im folgenden beschrieben.
Es gibt einen JSON-String für Abonnements und einen für Produkte (siehe oben).
Pro Aufruf ist es nur möglich entweder ein Produkt oder ein Abonnement zu übergeben.
{
"callbackurl": "https://www.providershop.de/HandleOrderResponse.php",
"parametercacheid": "0e81f10f-6de8-4edc-cdcf-de96cf61624c",
"abo": {
"monthlycosts": "25.70",
"monthlyservicedescription": "5 3D-Rundgänge",
"durationinmonth": "6",
"noticeperiod": "bis 3 Monate vor Vertragsende",
"automaticrenewal": "12 Monate",
"circleofusers": "customer"
},
"timestamp": 1565689180,
"signature": "649ee3dfbfb53187a9b2b66fafb658df24ca037c6de473fe"
}- “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. Beim Abonnement ist jede monatliche Abbuchung eine Transaktion. Diese soll von Ihnen gespeichert werden für spätere Verarbeitungszwecke sowie zur Nachverfolgbarkeit
- “aboid” : Eine eindeutige ID des Abonnements. 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.
- “message”: Liefert einen Fehlertext, sofern ein “error” zurückgegeben wurde. (Fehlertexte siehe unten)
- “timestamp”
- “signature”
- “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.
- “abo”:
- “monthlycosts”: monatliche Kosten des Abonnements
- “monthlyservicedescription”: Beschreibung des Produkts, für welches das Abonnement abgeschlossen wird
- “durationinmonth”: Laufzeit in Monaten
- “noticeperiod”: Kündigungsfrist
- “automaticrenewal”: Zeitraum der automatischen Verlängerung
- “circleofusers”: Benutzerkreis, für den gekauft wurde. Mögliche Werte: Mandant (customer), Bürogruppe (group), Benutzer (user)
- “timestamp”: Hier soll ein timestamp generiert werden, der in die Signatur einfließt und sie somit eindeutig macht
- “signature”: Diese muss über den JSON-String gebildet werden, damit die Gültigkeit validiert werden kann. (siehe Erläuterung zur Signatur)
Es handelt sich bei allen Parametern um Pflichtparameter.
Alle Abo-Parameter, außer der Preise, werden nur für die Ausgabe genutzt.
“circleofusers” gibt an, für welchen Benutzerkreis der Kauf gemacht wurde (→ siehe Bestellungen für mehrere Benutzer).
Die Fehlertexte sowie die Signierung des JSON-String sind die gleichen wie beim Einmalkauf eines Produktes.
Hinweis, wenn Abo-Zahlung fehlschlägt:
Es kann passieren, dass der monatliche Abo-Betrag nicht eingezogen werden kann, z.B. weil das Konto des Kunden nicht gedeckt ist, das Konto aufgelöst wurde oder der Betrag aus anderen Gründen nicht eingezogen werden konnte.
In diesem Fall erhalten Sie und der Kunde von uns eine E-Mail, dass der Abo-Betrag nicht eingezogen werden konnte. Jeweils sieben Tage später wird ein zweites und drittes Mal versucht, den Betrag erneut einzuziehen. Sie und der Kunde werden per E-Mail informiert.
Nach 3 fehlgeschlagenen Versuchen, den Betrag einzuziehen, ist der Einzug des Abobetrags für diesen Monat gescheitert und Sie erhalten darüber eine E-Mail.
D.h. danach sind Sie dann verantwortlich, den fehlenden Betrag dem Kunden in Rechnung zu stellen. Das können Sie z.B. über den Nachzahlungslink bequem durchführen.
3D-Secure: Bei Käufen ist manchmal eine Bestätigung des Kunden durch 3D-Secure (3DS2) notwendig. Im Regelfall kommen nach Abschluss eines Abonnements keine weiteren Abfragen durch 3DV2-Secure bei folgenden, wiederkehrenden Zahlungen. Der Kunde gibt bei der ersten Zahlung die Freigabe, dass auch die zukünftigen Zahlungen über den gleichen Betrag ohne 3DS2 passieren können.
In seltenen Fällen, bei denen eine Abbuchung aber trotzdem aufgrund von 3DS2 fehlschlägt, wird der fällige Betrag über einen Nachzahlungslink eingezogen. Bei einer solchen fehlgeschlagenen Transaktion wird ein Nachzahlungslink per Mail an den Käufer versendet. Sie als Anbieter erhalten eine Mail zur Information. Es werden in diesem Fall keine weiteren Versuche zum Abbuchen mehr unternommen.
Das Abo bleibt weiterhin eingerichtet, solange es nicht durch Sie gekündigt wird, sodass im nächsten Monat der Abo-Betrag wieder eingezogen wird.
Abonnements kündigen:
Die Abonnements laufen nicht automatisch aus. Soll ein Abonnement beendet werden, können Sie das Abonnement über die GUI in Ihrem onOffice-Anbieter-Mandant kündigen.
Dazu rufen Sie den Menüpunkt „Marketplace >> Anbieterkonto“ auf. Beim Klick auf das „Sanduhr“-Icon öffnet sich eine Ansicht, in der Sie das Kündigungsdatum für das Abonnement einstellen können. Nach diesem Datum werden keine Abbuchungen mehr getätigt.
API-Call zum Beenden eines Abonnements:
Die Abonnements laufen nicht automatisch aus. Soll ein Abonnement beendet werden, teilen Sie uns dies per API mit. Beim API-Call für das Beenden eines Abonnements wird das “cancelationDate” übergeben. Ab diesem Datum (inkl.) werden keine Abbuchungen mehr getätigt.
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:do",
"resourceid": "",
"identifier": "",
"resourcetype": "marketplaceCancelAbo",
"parameters": {
"aboid": "5",
"cancelationDate": "2019-10-05"
}
}Rechnungsstellung:
onOffice stellt den Kunden im Marketplace beim Kauf keine Rechnung aus, d.h. es liegt in Ihrer Verantwortung dem Kunden eine Rechnung zu stellen. Sie sind verpflichtet dem Kunden eine Rechnung auszustellen, da durch den Kauf Ihrer Services oder Produkte ein rechtsverbindliches Geschäft zustande kommt.
API-Abruf „Daten des Rechnungsempfängers“
Um die Rechnungsstellung zu automatisieren, können Sie die Daten des Rechnungsempfängers mit dem API-Call „Daten des Rechnungsempfängers“ auslesen.
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:get",
"resourceid": "",
"identifier": "",
"resourcetype": "getMarketplaceInvoiceRecipient",
"parameters": {
"transactionid": "12345678",
"userid": "123"
}
}- Notwendige Parameter sind „transactionid“ und „userid“
- Country wird bei API-Aufruf als ISO 3166-1 alpha-3 Wert zurückgegeben.
- API Fehlermeldungen:
- 184: User id is not existing or inactive (INFO: User id in the order is not the same as the transaction buying user id)
- 188: The user data could not be found
- 189: The transaction could not be found
- 190: The time to call the transaction has expired
Alle im Marketplace benutzen API-Calls sind auch auf der offiziellen API-Dokumentation beschrieben.
Automatisierte Rechnungsstellung – Abfragen des Rechnungsempfängers
Bisher wurden lediglich Kunden-IDs und API-Keys gespeichert. Hinter einer Kunden-ID können X Rechnungsempfänger stehen.
In einer onOffice Kundenversion können beliebig viele Benutzer arbeiten (in der größten Kundenversion sind es über 1000 Benutzer). Wenn die Makler zwar als Franchisenehmer bei einem großen Netzwerk angestellt sind, aber trotzdem selbstständig arbeiten, verfügen sie über ein eigenes Gruppen- oder Benutzerkonto beim Payment Provider. Die Rechnung muss dann entsprechend auf den jeweiligen Makler ausgestellt werden.
Als Anbieter können Sie die Rechnungsstellung automatisieren oder manuell durchführen. onOffice schickt zu jeder Buchung eine E-Mail mit den Daten des jeweiligen Rechnungsempfängers. Im Falle einer Automatisierung lassen sich beim Kauf die Daten des Rechnungsempfängers über den API-Call „Daten des Rechnungsempfängers“ bei onOffice erfragen.
- Im Zahlungsdialog bestätigt der Kunde seinen Kauf. onOffice schickt dem Anbieter die Info, dass der Kauf erfolgreich durchgeführt wurde. Dieses Event dient Ihnen als Auslöser für die Abfrage des Rechnungsempfängers.
- Der Rechnungsempfänger wird über den API-Call „Daten des Rechnungsempfängers“ ausgelesen…
- …und bei Ihnen im System für die Rechnungsstellung verbucht.
Provision
Nachdem der Zahlungsvorgang beim Payment Provider angestoßen wurde, wird der Betrag beim Kunden abgebucht. Davon geht eine Provision an onOffice, der restliche Betrag wird auf das Konto des Anbieters transferiert. Sie können sich über einen Payout in Ihrer Anbieterversion (Production) den Betrag auszahlen lassen.
Von der Provision werden u.a. alle Gebühren für den Payment Provider abgeführt. Als Basis für die Provisionsberechnung dient der Nettopreis des Produkts.
Die Dienstleistung von Mangopay ist damit für Sie als Anbieter kostenfrei.
Ablauf bei Zahlungsproblemen und fehlgeschlagenen Transaktionen
Allgemein:
Besteht ein Problem mit einer Zahlung (SEPA oder Kreditkarte) bzw. ist eine Transaktion fehlgeschlagen, bitten wir den Kunden im ersten Schritt zu prüfen, ob auf seiner Seite ein Grund vorliegen könnte (z.B. Konto nicht gedeckt, Limit auf der Karte) und die Transaktion dann erneut zu versuchen.
Danach raten wir den Kunden, Sie als Anbieter zu kontaktieren mit Angabe der Transaktionsnummer, damit Sie prüfen können, ob ein Problem auf Ihrer Seite vorliegt. Falls bei der Bestellung ein Fehler passiert, wird ein Errorcode an Sie zurückgeliefert, die evtl. auf die mögliche Ursache schließen lässt.
Ist das Problem behoben, können Sie den Kunden bitten die Transaktion erneut durchzuführen oder können ggfs. einen Nachzahlungslink per Mail an den Kunden schicken. Bei Klick auf den Link in der E-Mail öffnet sich das Bestellpopup. Der Kunde kann den Betrag dann direkt dort bezahlen, falls er die Transaktion noch durchführen möchte.
Falls weiterhin Probleme bestehen, raten wir dem Kunden sich an den onOffice-Support zu wenden, wo wir dann die Transaktion prüfen können.
Einmalzahlungen mit SEPA:
Bei Käufen über eine Bankverbindung mit SEPA-Mandat kann es einige Werktage dauern, bis die Überweisung abgeschlossen ist. Solange wird die Transaktion bei Ihren Kunden als „in Bearbeitung“ in der Transaktionsliste gekennzeichnet. Der gebuchte Service soll in der Regel schon direkt nach Kauf genutzt werden können.
Sollte die Überweisung aus irgendwelchen Gründen fehlschlagen, werden wir Sie als Anbieter darüber per E-Mail verständigen. Sie können Ihrem Kunden dann einen Nachzahlungslink per Mail zuschicken, um die Transaktion abschließen zu können. Über den Link öffnet sich das Bestellpopup und der Kunde kann den Kauf nachträglich durchführen.
Disputes
In seltenen Fällen können bei Käufen Disputes auftreten, d.h. dass ein Kunde die Zahlung bei der Bank zurückfordert. Das Geld wird dann zunächst bei onOffice abgebucht. Sie erhalten eine Mail von uns, wo Sie aufgefordert werden die entsprechende Transaktion in Ihrem Anbietermandanten zu stornieren. Der Käufer wird ebenfalls darüber per E-Mail informiert.
Dies können Sie im Anbietermandanten unter „Marketplace >> Anbieterkonto“ über das „Pfeil zurück“-Icon „Buchung stornieren“ bei den einzelnen Transaktionen auslösen. Sofern das nicht in einem gewissen Zeitraum passiert ist, würde onOffice die Stornierung bei Ihnen im Anbietermandanten durchführen.
Wenn für eine Transaktion ein Dispute registriert wurde, erhält die Transaktion in der Transaktionsliste den Status “Klärungsbedarf”. Hinweis: Es gibt auch Disputes die nicht storniert werden können, weil sie möglicherweise nicht anfechtbar sind.
Nachträgliche Kosten abrechnen
Es kann der Fall auftreten, dass sich der Umfang der Bestellung durch nachträgliche Kommunikation mit dem Kunden ändert oder dass eine Abbuchung fehlschlägt, obwohl der Kunde Ihren Service schon nutzen kann (z.B. bei SEPA-Zahlungen oder laufenden Abozahlungen). Dann müssen die Kosten nachträglich abgerechnet werden.
Am Beispiel der Grundriss-Optimierung könnte das wie folgt aussehen:
Der Kunde bestellt die Optimierung eines Grundrisses zum Preis von 14,95€. Er beachtet die Begrenzung des Anbieters nicht und bestellt die Optimierung mit einer zu großen Fläche und Zimmeranzahl (z.B. 340m², 18 Zimmer). Der Grundrissanbieter kontaktiert ihn und verweist auf den dafür zu zahlenden Betrag, mit dem sich der Kunde einverstanden erklärt. Eine Summe X muss nachberechnet werden.
Der Ablauf gestaltet sich wie folgt:
- Der Grundrissanbieter schickt dem Kunden eine E-Mail, in der ein Link enthalten ist, der den Bezahlvorgang anstößt.
Dieser Link setzt sich wie im folgenden Abschnitt „Aufbau des Links zur nachträglichen Abrechnung“ beschrieben zusammen.
- Der Kunde muss beim Aufruf des Links in onOffice mit seinem Benutzer eingeloggt sein. Ist das nicht der Fall, wird er dazu aufgefordert, sich einzuloggen.
- Daraufhin baut sich der Zahlungsdialog auf.
- Bestätigt der Kunde den Dialog, werden die Kosten übertragen.
- Der Anbieter schickt dem Kunden eine E-Mail mit dem signierten Link zum Zahlungsdialog.
- Der Kunde bestätigt die Zahlung und der Anbieter wird über die Bestätigung der Zahlung informiert.
Nachzahlungen verschicken / Generator für den Nachzahlungslink
In Ihrem Anbietermandant haben Sie die Möglichkeit einen Nachzahlungslink zu generieren, den Sie an Ihren Kunden verschicken können. Der Nachzahlungslink führt den Kunden auf die Lightbox für den Kauf, wo er die Nachzahlung bestätigt. Nutzen Sie dazu das Euro-Icon bei jeder Transaktion in Ihrem Anbieterkonto unter „Marketplace >> Anbieterkonto“.
Es öffnet sich eine Lightbox, in der Sie die Bezeichnung der Zusatzleistung und den Preis angeben. Daraufhin wird der Nachzahlungs-Link generiert. Diesen können Sie über „Nachzahlungslink per E-Mail versenden“ direkt an Ihren Kunden senden. Dafür wird eine Standard-Mailvorlage mit Absender „noreply@onoffice.de“ genutzt.
Oder Sie verschicken den generierten Link selbst an Ihren Kunden mit Ihrer eigenen Vorlage.
Vorlage zur nachträglichen Abrechnung
Es handelt sich hierbei immer um die Nachzahlung zu einem bereits getätigten Kauf über den Marketplace. Dabei kann es sich um einen einmaligen Kauf oder um ein Abonnement handeln. Die E-Mail an den Kunden zur nachträglichen Abrechnung definieren Sie. Sie könnte z.B. wie in der Abbildung zu sehen aufgebaut sein. Diese Vorlage können Sie hier als HTML für Ihre Verwendung runterladen.
Nach Klick auf „Zusatzleistung hier bestellen“ öffnet sich die Lightbox für die Zahlung.
Prüfen auf Gültigkeit des PSP-Kontos:
Wir prüfen anhand der User-ID, ob der User zum Zeitpunkt des Aufrufs über ein aktives Mangopay-Konto verfügt.
Prüfen der Signatur und aktive Sitzung:
Beim Ausführen des Links wird geprüft, ob der Link korrekt signiert ist.
Außerdem kann der Link nur aufgerufen werden, wenn der Benutzer mit seinem Account (aus dem die ursprüngliche Bestellung getätigt wurde) im angegebenen Mandanten eingeloggt ist. Ist er nicht eingeloggt, öffnet sich eine Login-Maske. Nach erfolgreichem Login kann der Link dann aufgerufen werden. Der Empfänger muss den Link im gleichen Browser aufrufen, in dem die onOffice-Sitzung läuft.
This post is also available in: Englisch