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.

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. Die meisten Marketplace-Anbieter laufen momentan noch im Sandbox-Modus und werden jetzt nach und nach auf Production-Modus umgestellt. 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. Benutzen Sie die ersten 4 Testkarten im Bereich VISA/MC unter „For payments under 50€ you can use these cards“. Diese erlauben Transaktionen bis 500€ (Fünfhundert). Höhere Beträge als 500€ funktionieren in der Testumgebung nicht, da 3D Secure notwendig ist. Bei Transaktionen mit Beträgen über 500€ wird eine Fehlermeldung ausgegeben.

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.

Transaktionsliste

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):

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. Bei Käufen über 500 € wird der Kunde 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. 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:

{
  "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 5 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
- “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.

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¶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=26.47

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

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 6 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
- “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 Abo-Betrags 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.

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"
  }
}

API-Abruf „Daten des Rechnungsempfängers“

{
  "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:get",
  "resourceid": "",
  "identifier": "",
  "resourcetype": "getMarketplaceInvoiceRecipient",
  "parameters": {
    "transactionid": "12345678",
    "userid": "123"
  }
}

Um die Rechnungsstellung zu automatisieren, können Sie die Daten des Rechnungsempfängers mit dem API-Call „Daten des Rechnungsempfängers“ auslesen.

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.

Von der Provision werden u.a. alle Gebühren für den Payment Provider abgeführt.

Die Dienstleistung von Mangopay ist damit für Sie als Anbieter kostenfrei.

Nachträgliche Kosten abrechnen

Tritt der Fall auf, dass sich der Umfang der Bestellung ändert, müssen die Kosten nachträglich abgerechnet werden. Das kann beispielsweise passieren, wenn sich der Leistungsumfang durch nachträgliche Kommunikation mit dem Kunden ändert.

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“.

Icon für Nachzahlungsgenerator

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.

Icon für Nachzahlunglink

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.

Nachzahlungen

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