Beschreibung der Payment-Schnittstelle und Möglichkeiten der Anbindung an Ihr E-Commerce-System

Transkript

1 Beschreibung der Payment-Schnittstelle und Möglichkeiten der Anbindung an Ihr E-Commerce-System Handbuch für E-Commerce-Anbieter Herausgegeben: Version: API Deutschsprachige Original-Anleitung

2 Copyright : Kein Teil der Dokumentation darf ohne schriftliche Genehmigung der ClickandBuy International Ltd. reproduziert oder unter Verwendung elektronischer Systeme verarbeitet, vervielfältigt oder verbreitet werden. ClickandBuy International Ltd. ist bemüht, ihre Produkte jeweils nach neuesten Erkenntnissen zu erstellen. Deren Richtigkeit sowie inhaltliche und technische Fehlerfreiheit wird gleichwohl ausdrücklich nicht zugesichert. ClickandBuy International Ltd. gibt auch keine Zusicherung für die Anwendbarkeit bzw. Verwendbarkeit ihrer Produkte zu einem bestimmten Zweck. Die Auswahl der Produkte, deren Einsatz und Nutzung fällt ausschließlich in den Verantwortungsbereich des Kunden. Änderungen an diesem Dokument sind ClickandBuy International Ltd. ohne Vorankündigung jederzeit vorbehalten.

3 Inhaltsverzeichnis Inhaltsverzeichnis 1 Einleitung Über ClickandBuy Grundsätzliche Funktionsweise Die Zielgruppen dieses Handbuchs Die Inhalte dieses Handbuchs Gestaltungsmerkmale des Handbuchs Verwendete Fachbegriffe Die Anwendungsmöglichkeiten von ClickandBuy Hinweise und Plug-Ins zur Anbindung an Ihr E-Commerce-System Einmalzahlung Billing Agreement-Modelle Bezahlvorgänge vor dem Ausführen sammeln Zahlungsvorgänge bei Wett-Anbietern Downloads Mitgliedsbereiche und virtuelle Guthaben Auslandsgeschäfte Rückabwicklungen Die Funktionalitäten von ClickandBuy Allgemeines Die API-Funktionselemente Calls Praktische Bedeutung der Transaction Calls (Requests) Praktische Bedeutung der Batch Calls Praktische Bedeutung der Accounting Calls (Requests) Der Merchant Messaging Service (MMS) Allgemeines Grundlegendes in der Übersicht Protokolle und Referenz-URLs Testumgebung ( Sandbox ) Erläuterungen zur Authentifikation Die Prozesse iii

4 Inhaltsverzeichnis 6.1 Der einfache Bezahlprozess Initiale Autorisierung und wiederkehrende Zahlungen Der Batchprozess Sonderfall der Bezahlart: Vorkasse Die Calls (Aufrufe) PayRequest (Einzeltransaktion mit Kundeninteraktion) PayRequestRecurring (Einzeltransaktion ohne Kundeninteraktion) RefundRequest (Aufruf zur Rückbuchung) CancelRequest (Aufruf zur Stornierung) CreditRequest (Aufruf zur Gutschrift) StatusRequest (Abfrage des Transaktionsstatus) CreateBatch (Stapelverabeitung) AddBatchItem (Stapeldatei füllen) ExecuteBatch (Stapelverabeitung starten) GetBatchStatus (Statusabfrage der Stapelverabeitung) CancelBatch (Stapelverabeitungsdatei verwerfen) GetAccountingDocuments (Abruf von Abrechnungsdokumenten) Schnelleinstieg Implementierung Warenkorb in Rechnung stellen Wiederkehrende Zahlung Sammeln/Stapelverarbeitung Digitale Güter Rückabwicklungen Der Merchant Messaging Service (MMS) Events individuell einrichten Voraussetzungen für die Event-Übermittlung Zur Authentifikation des XML Die XML-Schema-Definitionen (XSDs) Definition der obersten Typen: pay_1_1_0.xsd Typen der Bezahlarten: PayTypes_1_1_0.xsd SOAP-Typen: SOAPTypes_1_1_0.xsd MMS-Typen: mms_1_1_0.xsd...94 iv

5 Inhaltsverzeichnis 11 Die Status in den Transaktionen PayTransaction und PayTransactionRecurring RefundTransaction CreditTransaction Batch BatchItem RecurringPaymentAuthorization Die Fehlercodes Arten von Fehlercodes Auflistung der Fehlercodes Der Testmode Funktionsweise des Testmodes Die Transaktionen mit den Testparametern XML-Beispiele Notation des PayRequest Notation des StatusRequest Notation einiger MMS-Events v

6 TEIL 1: ALLGEMEINE ÜBERSICHT

7 TEIL 1 ALLGEMEINE ÜBERSICHT 1 Einleitung Das vorliegende Handbuch richtet sich an Betreiber von E-Commerce-Unternehmen, die ihre Bezahlprozesse optimieren möchten. Clickandbuy bietet für viele E-Shops Plug-Ins, mit denen Sie ClickandBuy als Bezahlmethode schnell und problemlos im Shop einbinden können. Eine Liste mit allen unterstützten E-Shops finden Sie im Abschnitt 2.1. Wir empfehlen Ihnen aber, den ersten Teil dieses Handbuchs im Hinblick auf Geschäftsmodelle, bei denen ClickandBuy Sie unterstützen kann, zu studieren. 1.1 Über ClickandBuy ClickandBuy ist eines der führenden Bezahlsysteme im Internet. Mit dem von McAfee zertifizierten Online-Payment-System bezahlen bereits über 13 Millionen Menschen ihre Einkäufe im Internet. Mehr als Online-Händler verwenden das E-Payment-System ClickandBuy zur Abrechnung für E-Commerce, Online-Entertainment und Paid Content & Services. Das 1999 gegründete Internet-Bezahlsystem wird von der ClickandBuy International Ltd. in London betrieben. Seit dem 1. April 2010 ist ClickandBuy eine 100%ige Tochtergesellschaft der Deutschen Telekom AG. ClickandBuy ist von der britischen Finanzaufsichtsbehörde FCA (Financial Conduct Authority) als E-Geldinstitut lizensiert. Als Full Service System (Komplett-Bezahlsystem) bietet ClickandBuy 50 nationale und internationale Bezahlmethoden in 120 Währungen an. Diese Erfahrung ermöglicht es ClickandBuy, nunmehr die gesamte Funktionalität in einer einzigen Schnittstelle zu bündeln. Mit diesem Interface kann ClickandBuy alle denkbaren E-Commerce-Lösungen und Bezahlarten abbilden. Das ClickandBuy-System Das ClickandBuy-System bietet eine intelligente Anbindung für komplexe, individuell erstellte E-Commerce-Anwendungen mit eigener Architektur. Auch gewachsene Altsysteme der Warenwirtschaft können das ClickandBuy-System vorteilhaft für sich nutzen. Natürlich lassen sich auch weniger komplexe, standardisierte Onlineshop- Lösungen mühelos mit der ClickandBuy-Schnittstelle verbinden. Beim ClickandBuy-System handelt es sich um ein eigenständiges Produkt des Unternehmens ClickandBuy. 7

8 TEIL 1 ALLGEMEINE ÜBERSICHT 1.2 Grundsätzliche Funktionsweise ClickandBuy übernimmt sämtliche Bezahlvorgänge Ihres E-Commerce-Systems. Hierfür müssen Sie Ihre E-Commerce-Anwendung einmal an die Programmierschnittstelle von ClickandBuy anbinden. Ihr Kunde registriert sich einmal bei ClickandBuy und kann dann beim Bezahlen in Ihrem Shop direkt mit ClickandBuy Benutzername und Passwort bezahlen. Über die zahlreichen Vorteile, die Ihr Kunde hierdurch genießt, informiert Sie unser Portal unter Die Zielgruppen dieses Handbuchs Kaufmännische Entscheider Einige Teile beschreiben die Funktionalität des ClickandBuy-Bezahlsystems aus der Sicht der kaufmännisch Verantwortlichen von E- Commerce-Anwendungen. Diese Informationen sind mit dem nebenstehenden Piktogramm gekennzeichnet. Techniker Andere Teile des Handbuchs beschreiben den technischen Hintergrund des ClickandBuy-Systems. Hier richten wir uns an die IT-Fachleute und Entwickler Ihres E-Commerce-Systems. Diese Informationen sind mit dem nebenstehenden Piktogramm gekennzeichnet. 1.4 Die Inhalte dieses Handbuchs Teil 1 Kapitel 2: Die Anwendungsmöglichkeiten von ClickandBuy Hier erfahren Betreiber, wie ClickandBuy die Geschäftsprozesse zu ihrem Vorteil unterstützt. Kapitel 3: Die Funktionalitäten von ClickandBuy In Grundzügen erläutern wir hier den technischen Hintergrund (die API) der ClickandBuy-Funktionalitäten. Teil 2 Technische Implementierung Hier sind technische Abläufe und Definitionen aufgelistet. Dieser Teil des Handbuchs ist speziell an Entwickler gerichtet und erklärt den technischen Aufbau der Schnittstelle. 8

9 TEIL 1 ALLGEMEINE ÜBERSICHT 1.5 Gestaltungsmerkmale des Handbuchs Weitere Auszeichnungen Wichtige Hinweise sind mit dem nebenstehenden Piktogramm gekennzeichnet. Verweise auf eine andere Textstelle oder ein anderes Dokument sind mit dem nebenstehenden Piktogramm gekennzeichnet. Transaction Calls Englische Begriffe oder Ausdrücke aus der ClickandBuy- Programmierschnittstelle (API) sind kursiv gestellt. 1.6 Verwendete Fachbegriffe In diesem Handbuch verwenden wir folgende Fachbegriffe: Begriff Abonnement API Batch Bezahl-Link Billing Agreement Call Erklärung Im technischen Kontext: die Prozessierung wiederkehrender Daten; der Bezug von Events (siehe da) im Zusammenhang mit dem MMS (siehe da) Allgemeine Bedeutung: ClickandBuy unterstützt auch den Geschäftsvorfall Abonnement. (Siehe Kapitel 2) Schnittstelle für die Implementierung des ClickandBuy-Systems in Ihre E-Commerce-Anwendung. Stapelverarbeitung. Sie können mehrere Anfragen an ClickandBuy zu einem Arbeitsablauf zusammenfassen. Nachdem Ihr System einen Aufruf PayTransaction oder PayTransactionRecurring an ClickandBuy abgesetzt hat, antwortet ClickandBuy mit einem Bezahl-Link (einer URL). Für die initiale Autorisierung der wiederkehrenden Zahlung geht der Kunde ein Billing Agreement (eine Einwilligung zur Abrechnung) mit Ihnen ein. Aufruf Ihres E-Commerce-Systems an ClickandBuy. 9

10 TEIL 1 ALLGEMEINE ÜBERSICHT Checkout-Seite, User-Interaction- Page Event Wenn der Kunde in Ihrem System die Bezahlart ClickandBuy gewählt hat, gelangt er auf die Checkout-Seite von ClickandBuy. Dort bekommt er nach dem Login die Details des Zahlungsvorgangs angezeigt, um den Zahlungsvorgang zu bestätigen. Statusänderungen von Bezahlvorgängen, die die ClickandBuy- API automatisch an Ihr System ausgibt (z. B. SUCCESS für eine erfolgte Zahlung. Siehe auch Abonnement.) Merchant Landing Page Merchant Messaging Service (MMS) Plug-In Request Response Sofortkauf SOAP Status Transaktion Transaction Call Nachdem der Kunde auf der Checkout-Seite (siehe da) die Zahlung vorgenommen hat, kommt er wieder zurück auf Ihr System. Der Benachrichtigungsservice der ClickandBuy-API, der Sie in Nahzeit über jede Statusänderung informiert (siehe auch Status ). Fertige Installationssoftware von ClickandBuy für eine Reihe von verbreiteten E-Commerce-Anwendungen. Anfrage oder Aufforderung aus Ihrem System an ClickandBuy (z. B. StatusRequest: Anfrage des aktuellen Status eines Bezahlvorgangs). Antwort von ClickandBuy auf einen Call (siehe da) des E-Commerce-Systems (siehe auch Request). Ein Anwendungsfall der wiederkehrenden Zahlung (siehe da), der auch als One-Click-Payment bekannt ist. Ihr Kunde gibt Ihnen einmalig die Erlaubnis, in seinem Namen eine Zahlung einzuleiten, ohne dass er Kunde diese durch sein Login bestätigen muss. Standard-Webprotokoll (Simple Object Access Protocol), das von Ihrem System benötigt wird, um den XML-Webservice (siehe da) von ClickandBuy nutzen zu können. Die Transaktionen (siehe da) durchlaufen verschiedene Status bis zum Abschluss der Verrechnung. Die einzelnen Aktionen zwischen Ihrem System und ClickandBuy (z. B. ein Bezahlvorgang) heißen Transaktionen. Aufruf an ClickandBuy (wie Request; siehe da). 10

11 TEIL 1 ALLGEMEINE ÜBERSICHT Warenkorbmodell Wiederkehrende Zahlung WSDL XML In diesem Handbuch ist damit der Verkauf von Waren (physische oder digitale Güter) in einem einzigen Vorgang gemeint (im Gegensatz z. B. zur wiederkehrenden Zahlung, siehe da). Mehrmaliger Geldeinzug innerhalb eines Geschäftsvorgangs. Dieses Zahlungsmodell können Sie für eine Reihe von Anwendungsfällen nutzen, z. B. ein Abo, Ratenzahlung u. a. In der ClickandBuy-API benötigen Sie nur eine einmalige initiale Autorisierung vom Kunden (siehe Billing Agreement). Die WSDL (Web Services Description Language) enthält die gesamte Beschreibung der API. XML (Extensible Markup Language) ist ein allgemein zur Verfügung stehendes Datenformat, das ClickandBuy für den bequemen Austausch mit anderen Systemen nutzt. 11

12 TEIL 1 ALLGEMEINE ÜBERSICHT 2 Die Anwendungsmöglichkeiten von ClickandBuy In diesem Kapitel möchten wir Ihnen einige mögliche Anwendungsfälle des Bezahlsystems ClickandBuy vorstellen. Lesen Sie hier, wie effizient ClickandBuy Ihre geschäftlichen Abläufe unterstützt. Folgende Geschäftsmodelle werden vorgestellt: Einmalzahlung Teillieferung Ratenzahlung Sofortkauf (One-Click-Payment) Abonnement Micropayment Bezahlvorgänge vor dem Ausführen sammeln Zahlungsvorgänge bei Wett-Anbietern Downloads Mitgliedsbereiche und virtuelle Guthaben Auslandsgeschäfte Rückabwicklungen 12

13 TEIL 1 ALLGEMEINE ÜBERSICHT 2.1 Hinweise und Plug-Ins zur Anbindung an Ihr E-Commerce-System Sie können das ClickandBuy-System an jede denkbare E-Commerce-Lösung anbinden ClickandBuy und gängige E-Commerce-Anwendungen Für eine Reihe von weit verbreiteten E-Commerce-Anwendungen, wie etwa Magento, OXID, oscommerce oder xtcommerce, stellt ClickandBuy fertige Plug-Ins zur Verfügung. Unter folgender URL finden Sie eine Liste der aktuell unterstützten E-Commerce- Anwendungen und können Plug-Ins für Ihr Shopsystem herunterladen: Sie müssen diese Plug-Ins nur herunterladen und installieren. Die ClickandBuy-API ist dadurch mit Ihrem System verbunden. Die Dokumentation zu dem jeweiligen Plug-In ermöglicht Ihnen, die Anbindung ohne spezielle Computerkenntnisse vorzunehmen ClickandBuy und individuelle E-Commerce-Lösungen Benutzen Sie eine andere E-Commerce-Lösung oder haben Sie Ihre E-Commerce- Anwendung individuell entwickelt, können Sie diese ebenfalls mit ClickandBuy verbinden. Hierfür stellt ClickandBuy Beispiel-Skripte in verschiedenen Programmiersprachen zur Verfügung. Als registrierter Anbieter erhalten Sie die Skripte unter folgendem Link: Bitte beachten Sie, dass zur individuellen Anbindung Ihres Systems solide IT- Kenntnisse erforderlich sind. 13

14 TEIL 1 ALLGEMEINE ÜBERSICHT 2.2 Einmalzahlung Betreiben Sie ein E-Commerce-System mit Warenkorbmodell, nimmt ClickandBuy Ihnen den Bezahlprozess ab. Hierbei spielt es keine Rolle, ob es sich um physische oder digitale Güter handelt. Ihre Kunden können zum Beispiel Elektroartikel oder Autozubehör ebenso bei Ihnen kaufen und mit ClickandBuy bezahlen wie MP3-Dateien oder Dokumente im PDF-Format. Wenn Ihr Kunde die Produkte also in den Warenkorb gelegt hat und auf der Übersicht der Zahlungsweisen angekommen ist, kann er die Option ClickandBuy wählen. Ihre E-Commerce-Anwendung übermittelt eine Anfrage unter anderem mit der relevanten Rechnungssumme (1) sowie anderen optionalen Informationen. Als Antwort sendet ClickandBuy unter anderem einen Bezahl-Link (2), das heißt eine nur für diese Transaktion gültige URL. Das E-Commerce-System ruft den Bezahl-Link auf und leitet den Kunden zu ClickandBuy. Nach erfolgreichem Login oder Registrierung wählt er die gewünschte Bezahlart und bestätigt die Zahlung (3). Nach dem Bezahlvorgang wird der Kunde wieder an die von Ihnen spezifizierte Seite zurückgegeben, so dass Sie Ihn weiter bedienen können. Für diesen einfachen Bezahlprozess findet eine einmalige Interaktion mit dem Kunden statt. ClickandBuy zieht dann das Geld vom Kundenkonto bzw. vom hinterlegten Bezahlmittel ein und verbucht gleichzeitig den Geldeingang auf Ihrem Anbieterkonto. Die Auszahlung der Umsätze erfolgt in von Ihnen definierten Zeiträumen. 14

15 TEIL 1 ALLGEMEINE ÜBERSICHT Sonderfall Vorkasse Die Bezahlart Vorkasse stellt eine Sonderfunktion unter den Bezahlarten dar. Der Kunde kann im regulären Bezahlprozess auf der ClickandBuy-Checkout-Seite die Variante Vorkasse auswählen, wenn er z. B. auf Grund von Sicherheitsbedenken und Vorbehalten gegen Zahlungen im Internet keine Zahlungsmitteldaten preisgeben will. Hat der Kunde die Rechnung dann bei ClickandBuy z. B. per Überweisung beglichen, werden Sie von ClickandBuy informiert und können die bestellte Ware ausliefern. Die Vorkasse ist beim Abonnement nicht möglich. 2.3 Billing Agreement-Modelle Für wiederkehrende Bezahlmodelle sieht ClickandBuy das Billing Agreement-Modell vor. Der Kunde gibt Ihnen eine Einzugsermächtigung für einzelne Bezahlvorgänge. Sie können das Billing Agreement durch eins oder mehrere der drei folgenden Limits begrenzen: die Zeit die Anzahl der Zahlungen die Höhe der Summe. Ein besonderes Leistungsmerkmal besteht darin, dass Sie die Limits kombinieren können. Dies ermöglicht individuelle Geschäftsmodelle mit Ihren Kunden. Darüber hinaus können Sie festlegen, ob Ihr Kunde das Billing Agreement widerrufen können soll. Ohne eine dieser Begrenzungen bleibt das Billing Agreement bis zum Widerruf des Kunden aktiv. Sie können das Billing Agreement wahlweise separat oder zusammen mit der initialen Transaktion stornieren. 15

16 TEIL 1 ALLGEMEINE ÜBERSICHT Abonnement Sie bieten ein Zweijahresabonnement für eine monatlich erscheinende Fachzeitschrift an. Oder Sie möchten einen täglich erscheinenden Online-Artikel für einen Monat als Abo zum Download anbieten. Wie beim Einzelkauf setzt Ihre E-Commerce-Anwendung eine Anfrage an ClickandBuy mit den Auftragsdetails ab (1). Die ClickandBuy-API reagiert auf die Anfrage wiederum unter anderem mit einer Redirect-URL, auf die der Kunde weitergeleitet wird. Dort loggt sich der Kunde ein oder registriert sich mit einen neuen Konto. Anschließend bestätigt er die Zahlungsdetails auf der Bezahlseite (2) und geht damit das Billing Agreement entsprechend der vorher definierten Rahmenbedingungen (Gültigkeit, Anzahl Belastungen, Gesamtsumme) ein. Zuletzt erfolgt die Bestätigung durch Ihr System (3). Im Unterschied zum einfachen Bezahlvorgang geht der Kunde in diesem Geschäfsmodell ein Billing Agreement ein, das heißt er gibt Ihnen eine Einzugsermächtigung für die wiederkehrenden Zahlungen. Sie können dann bequem eine Belastung des Kunden durchführen, ohne dass er jedes Mal seine Einwilligung geben muss, denn dies hat er mit dem ursprünglichen Billing Agreement bereits getan. Sie senden die Fachzeitschrift oder die Downloads monatlich bzw. täglich an die hinterlegte Post- oder -Adresse. Es kann auch ein Online-Zugriff auf die bezahlten Inhalte gewährt werden Zur Begleichung der wiederkehrenden Zahlungen sendet Ihre E-Commerce-Anwendung nur noch die Zahlungsanfrage an ClickandBuy, wobei Sie selbst die Intervalle der Belastung festlegen. Eine weitere Interaktion mit dem Kunden ist nicht notwendig. Die wiederkehrende Zahlung beim Abonnement kann durch Zeit, die Anzahl der Zahlungen oder die Gesamtsumme begrenzt werden (siehe vorheriger Abschnitt). Zusätzlich können Sie festlegen, ob der Kunde das Billing Agreement selbst widerrufen kann oder nicht. 16

17 TEIL 1 ALLGEMEINE ÜBERSICHT Teillieferung Teillieferungen können notwendig werden, wenn das Produkt aus versandtechnischen Gründen nicht im Ganzen oder wenn Teile der Bestellung erst in der Zukunft geliefert werden können. Solche Fälle, in denen Sie die Folgelieferungen bei der Erstbestellung unter Umständen nicht genau planen können, deckt ClickandBuy ebenfalls ab. Die Erlaubnis des Kunden, von seinem ClickandBuy-Konto wiederholende Zahlungen abzubuchen, erfolgt mittels Billing Agreement ähnlich wie beim Abonnement. Ihr Unternehmen setzt dann einfach bei jeder Auslieferung eines weiteren Produktteils eine Zahlungsanfrage an ClickandBuy ab. Die Autorisierung für wiederkehrende Zahlungen kann von Ihnen begrenzt werden. Die wiederkehrende Zahlung bei der Teillieferung ist z. B. begrenzt durch die Anzahl der bestellten Artikel. Sie endet automatisch, wenn die letzte Lieferung versendet wurde. 17

18 TEIL 1 ALLGEMEINE ÜBERSICHT Ratenzahlungen Wenn Sie Ihren Kunden Käufe mit Hilfe von Ratenzahlung erleichtern möchten, haben Sie keinen Mehraufwand im Bezahlprozess. Das ClickandBuy-System wickelt die Ratenzahlung mit der gleichen Technik des Billing Agreement ab wie beim Abonnement oder bei Teillieferungen. Zum Beispiel: Sie möchten eine flexible Ratenzahlung für eine Ware anbieten, die kostet. Option 1: 10 x 100 : zehn Zahlungen innerhalb von zwölf Monaten: Begrenzung durch die Höhe der Summe und die Zeit. Option 2: Maximal fünf Zahlungen, jeweils maximal 300 : Begrenzung durch Anzahl und Höhe der Summe. Option 3: Maximal fünf Zahlungen, zu zahlen innerhalb von zwölf Monaten: Begrenzung durch Anzahl und Zeit. Die Autorisierung ist begrenzt und endet bei Erreichen der Limits automatisch. Die Autorisierung lässt eine Begrenzung auf eine Gesamtsumme zu, jedoch nicht die Begrenzung der Höhe der Teilzahlungen. 18

19 TEIL 1 ALLGEMEINE ÜBERSICHT Sofortkauf ( One-Click-Payment ) Die Technik der wiederkehrenden Zahlung mittels Billing Agreement können Sie auch dann einsetzen, wenn Sie Ihrem Kunden einen Sofortkauf anbieten möchten. Ihr Kunde gibt Ihnen einmalig die Erlaubnis, ihn immer dann zu belasten, wenn er etwas kaufen möchte, ohne den Bezahlprozess erneut zu durchlaufen. Bei diesem auch als One-Click-Payment bekannten Prinzip muss Ihr Kunde bei einem Folgekauf keine weitere Einwilligung geben und kauft sofort mit einem Mausklick. Ihr Kunde hat dann den Status eines Stammkunden. Er ist bereits bei ClickandBuy bekannt und muss sich für den Bezahlvorgang nicht mehr legitimieren. Voraussetzung ist, dass er mit Ihnen ein Billing Agreement ohne Limitierung eingegangen ist. Beim Sofortkauf tritt ClickandBuy nur einmalig mit dem Kunden zur Bestätigung der Einzugserlaubnis in Kontakt. Alle weiteren Zuordnungen und Abbuchungen von Waren auf ein Billing Agreement werden vom Anbieter abgewickelt. Der Kunde loggt sich in Ihr System ein und zahlt entsprechend des bestehenden Billing Agreement mit nur einem Klick, ohne weitere Interaktion mit ClickandBuy. 19

20 TEIL 1 ALLGEMEINE ÜBERSICHT Micropayment Wenn Sie Online-Content zum Download anbieten, kann ClickandBuy Sie in der Abwicklung der Bezahlvorgänge unterstützen. Das Micropayment, also die Bezahlung von Kleinstsummen für Online-Inhalte, muss Ihr System nicht durch eine Flut von Einzelabwickungen belasten. Sie haben die Möglichkeit, die Bezahlvorgänge in einem Vorgang (Batch, siehe auch folgenden Abschnitt) zu sammeln. Sind genügend Einzelvorgänge gesammelt, kann Ihr System die Bezahlung an ClickandBuy in einem Vorgang übermitteln. 20

21 TEIL 1 ALLGEMEINE ÜBERSICHT 2.4 Bezahlvorgänge vor dem Ausführen sammeln Falls Sie bestimmte Bezahlprozesse erst sammeln möchten, bevor Sie sie als Transaktionsanfrage zu ClickandBuy schicken, steht Ihnen im ClickandBuy-System die Stapelverarbeitung (Batch-Prozessierung) zur Verfügung Bearbeitung durch verschiedene Personengruppen Das Sammeln von Transaktionsanfragen bietet sich immer dann an, wenn das Anlegen, Kontrollieren und Absenden durch verschiedene Personen in Ihrem Unternehmen ausgeführt werden soll. Zum Beispiel könnte eine Gruppe von Mitarbeitern Kundenbestellungen entgegennehmen. Eine andere Gruppe könnte etwa Kundenbeschwerden entgegennehmen. Diese Mitarbeiter würden dann die Transaktionen vorbereiten seien es Bezahlvorgänge oder Rückabwicklungen. Eine andere Personengruppe, die mit weiter reichenden Rechten ausgestattet ist, kann die Bestellungen oder Beschwerden dann später kontrollieren, ggf. freigeben und als Paket an ClickandBuy übermitteln Stapelverarbeitung in gewachsenen Altsystemen Möglicherweise erweist sich eine Echtzeitanbindung des ClickandBuy-Systems an Ihr historisch gewachsenes Warenwirtschaftssystem in einigen Systemteilen als schwierig. Hier kann die Stapelverarbeitung eine wichtige Aufgabe übernehmen. Mittels der Batch-Prozessierung können Sie zum Beispiel einmal täglich Gutschriften, Rückerstattungen oder Stornierungen aus Ihrem Warenwirtschaftssystem vorbereiten, dann in einem Batch zusammenführen und gesammelt ausführen. 2.5 Zahlungsvorgänge bei Wett-Anbietern Anbieter von Online-Wetten wissen, dass die Bezahlprozesse in Ihrem Unternehmen komplexer sind als beim einfachen Kauf. Ihr Kunde kann mittels ClickandBuy zunächst den Wetteinsatz leisten. Sie haben die Wahl auf welche Weise und mit welchem Abrechnungsmodell dies geschehen soll. Nutzen Sie Warenkorb, Abonnement, One-Click oder die API Calls, um Ihre eigene Lösung umzusetzen. Möchte Ihr Kunde seine Gewinne einlösen, können Sie ihm diese als Gutschrift per E- Mail oder Kundenreferenznummer oder als Rücktransaktion auf sein ClickandBuy- Konto zukommen lassen. Ebenso können Sie Gewinnausschüttungen und Gutschriften nach Ihren eigenen Wünschen, z. B. in regelmäßigen zeitlichen Abständen, umsetzen. 21

22 TEIL 1 ALLGEMEINE ÜBERSICHT 2.6 Downloads Wenn Downloads Ihr Geschäftsmodell bestimmen, kann ClickandBuy Sie im Bezahlprozess wirkungsvoll unterstützen, zum Beispiel bei Audiodateien Filmdateien Softwarelösungen Spielen oder einfach Texten und Bildern. Gerade bei kombinierten Angeboten wird häufig noch auf eine Bepreisung des Bezugs von Online-Content verzichtet zum Beispiel bei einer gedruckten und einer Online- Zeitschrift. Die Tendenz geht jedoch dahin, sich Online-Content (also etwa Zeitungsartikel) im Sinne des fairen Wettbewerbs mit einem geringen Betrag von wenigen Cent vergüten zu lassen. Der Bezahlvorgang bei Downloads ist für Sie und für Ihren Kunden nicht anders als beim Einzelkauf (siehe 1.1, Warenkorbmodell). 2.7 Mitgliedsbereiche und virtuelle Guthaben In einigen Online-Mitgliedsbereichen können Kunden ein virtuelles Guthaben erwerben. Dieses Bezahlmodell können Sie ebenfalls mit ClickandBuy abbilden. Je nach Gestaltung funktionieren die Bezahlvorgänge wie eine einfache oder wiederkehrende Zahlung. 2.8 Auslandsgeschäfte ClickandBuy rechnet global mit praktisch allen existierenden Währungen ab. Befindet sich Ihr E-Commerce-Unternehmen in einem anderen Währungsgebiet als Ihr Kunde, bezahlt Ihr Kunde in seiner Landeswährung. ClickandBuy unterstützt praktisch alle weltweit gültigen Währungen. Eine detaillierte Auflistung der unterstützten Währungen finden Sie unter folgendem Link: 22

23 TEIL 1 ALLGEMEINE ÜBERSICHT 2.9 Rückabwicklungen Mit ClickandBuy können Sie drei Arten von Rückabwicklungen realisieren: Rückerstattungen Gutschriften und Stornierungen Rückerstattungen Hat Ihr Kunde eine berechtigte Beschwerde angebracht oder können Sie eine bereits bezahlte Ware nicht liefern, so können Sie einen beliebigen Teilbetrag der Zahlung an den Kunden zurückbuchen. Dies kann für eine Zahlung auch mehrmals geschehen. Allerdings können insgesamt nicht mehr als 100 Prozent des Originalbetrages zurückerstattet werden. ClickandBuy bucht die Rückerstattung immer auf das ursprünglich verwendete Zahlungsmittel zurück. Sollte die Rückbuchung auf das verwendete Zahlungsmittel nicht unterstützt werden z. B. Boleto Bancário in Brasilien, bucht ClickandBuy den Wert als E-Geld auf das ClickandBuy-Kundenkonto zurück Gutschriften Sie können eine Zahlung an den Kunden auch dann ausführen, wenn vorher noch kein Geschäftsvorgang mit dem Kunden stattgefunden hat. Hierdurch haben Sie zum Beispiel die Möglichkeit, die Bestellung eines Abos mit einer Gutschrift aufzuwerten oder einem Kunden für eine Vermittlung einen Bonus auszuzahlen. Als Kundenreferenz dient wahlweise die Kundenreferenznummer oder die - Adresse. Dabei ist es irrelevant, ob bereits ein ClickandBuy-Konto unter dieser - Adresse besteht oder nicht. Ist dies nicht der Fall, erhält der Kunde neben einer generellen Informationsmail genauere Anleitungen, wie er ein Endkundenkonto anlegen und die Gutschrift annehmen kann. Für Gutschriften auf eine -Adresse können Sie eine eigene Gültigkeitsdauer definieren. Nach Ablauf der Gültigkeit wird die Gutschrift automatisch storniert. Gutschriften auf eine Kundenreferenznummer werden direkt dem Kundenaccount gutgeschrieben und müssen vom Kunden nicht explizit angenommen werden Stornierungen Falls Ihr Kunde eine Bestellung storniert hat oder Sie die Ware nicht liefern können, haben Sie die Möglichkeit, 100 % des bezahlten Betrags zurückzubuchen. ClickandBuy behandelt den Storno technisch wie eine Voll-Rückerstattung auf das verwendete Zahlungsmittel. Wenn das Zahlungsmittel eine Rückerstattung nicht unterstützt, können Sie den Betrag auf das E-Geld-Konto des Kunden zurückbuchen. 23

24 TEIL 1 ALLGEMEINE ÜBERSICHT 3 Die Funktionalitäten von ClickandBuy In diesem Kapitel beschreiben wir, mit welchen Funktionen die ClickandBuy-API die Anwendungen realisiert. Als Betreiber eines E-Commerce-Systems erfahren Sie hier, welche Vorteile die übersichtliche Architektur bietet. IT-Fachleute und Entwickler des E-Commerce-Systems erhalten hier eine erste Einführung in den technischen Hintergrund der API. Die vollständige API-Referenz ist im Anhang dargestellt. 3.1 Allgemeines Das ClickandBuy-System arbeitet mit einer offenen Programmierschnittstelle, basierend auf dem verbreiteten SOAP-Modell. In dieser API sind sämtliche Funktionalitäten des Systems enthalten. Das ClickandBuy-System ist offen für alle Funktionen Ihrer E-Commerce-Lösung. 3.2 Die API-Funktionselemente Calls Kernstück der Universal Payment -API bilden die Funktionsaufrufe, die so genannten Calls. Die Universal Payment API unterscheidet zwischen folgenden Call-Typen: Transaction Calls für die Bezahlprozesse Batch Calls für die Stapelverarbeitung Accounting Calls für die Abrechnungsprozesse Transaction Calls oder Requests Transaction Calls sind Anfragen (Requests), die Ihre E-Commerce-Anwendung bei einer Bezahltransaktion an das ClickandBuy-System sendet Batch Calls (Aufrufe zur Stapelverarbeitung) Batch Calls sind Funktionsaufrufe zur Steuerung einer Stapelverarbeitung. Mit den Batch Calls können Sie Bezahltransaktionen sammeln, bevor Sie sie ausführen Accounting Calls oder Requests Accounting Calls sind Anfragen (Requests), die Ihre E-Commerce-Anwendung bei Abruf der Abrechnungsdokumente an das ClickandBuy-System sendet. 24

25 TEIL 1 ALLGEMEINE ÜBERSICHT 3.3 Praktische Bedeutung der Transaction Calls (Requests) Die sechs Transaction Calls oder Requests bilden alle denkbaren Zahltransaktionen Ihres E-Commerce-Unternehmens ab PayRequest (Einzeltransaktion mit Kundeninteraktion) Den einfachen, einmaligen Bezahlvorgang realisiert der Transaction Call PayRequest. Ihre E-Commerce-Anwendung nutzt den PayRequest zum Beispiel für: das klassische Warenkorb-Shopping den Verkauf von digitalen Gütern per Zugriffsberechtigung oder Download das Bezahlen von Gebühren für Mitgliedsbereiche eine initiale Autorisierung für wiederkehrende Zahlungen (siehe nächsten Eintrag). 25

26 TEIL 1 ALLGEMEINE ÜBERSICHT Ablaufdiagramm Das folgende Diagramm zeigt den Ablauf der Transaktionsschritte am Beispiel eines Warenkorb-Kaufs: Erläuterung: Wenn Ihr Kunde sich für das Bezahlen über ClickandBuy entschieden hat, setzt Ihr E-Commerce-System einen PayRequest an ClickandBuy ab. ClickandBuy antwortet mit einer TransactionID und einem einmaligen Link (einer URL). Diese URL leitet den Kunden auf die ClickandBuy-Checkout-Seite zur Transaktionsbestätigung und Zahlungsinitiierung. Im Anschluss an den PayRequest setzen Sie einen zweiten Call StatusRequest an das ClickandBuy-System ab. Sie erhalten eine Information über Erfolg oder Nichterfolg. Sie entscheiden selbst, wie Sie Ihren Kunden anschließend informieren. Beim PayRequest findet also eine einmalige Interaktion mit dem Kunden statt. 26

27 TEIL 1 ALLGEMEINE ÜBERSICHT PayRequestRecurring (Einzeltransaktion ohne Kundeninteraktion) Einen wiederkehrenden Bezahlvorgang realisiert der Transaction Call PayRequestRecurring. Ihre E-Commerce-Anwendung nutzt den PayRequestRecurring zum Beispiel für: Abonnement Teillieferungen Ratenzahlungen den Sofortkauf das Bezahlen von Gebühren für Mitgliedsbereiche. Wiederkehrende Zahlungen können, müssen aber nicht, durch eine oder mehrere der folgenden Begrenzungen limitiert sein: die Höhe der Summe die Anzahl der Zahlungen den Zeitraum der Abzahlung. Sie können diese Limits kombinieren und dadurch zum Beispiel Ratenzahlungen flexibel gestalten (vgl. auch Kapitel 2, Die Anwendungsmöglichkeiten von ClickandBuy ). 27

28 TEIL 1 ALLGEMEINE ÜBERSICHT Auflaufdiagramm: Erläuterung: Zur initialen Autorisierung einer wiederkehrenden Zahlung nutzt die Universal Payment API ebenfalls den PayRequest (siehe vorheriger Abschnitt). ClickandBuy antwortet diesmal außer mit einer TransactionID und einem einmaligen Link (einer URL) auch mit der RPA, der Recurring Payment Authorization. Nachdem der Kunde seine Zustimmung zur wiederkehrenden Zahlung gegeben hat, ist für die restliche Zahlungsabwicklung keine Interaktion mehr notwendig. 28

29 TEIL 1 ALLGEMEINE ÜBERSICHT StatusRequest (Abfrage des Transaktionsstatus) Im Laufe des Bezahlvorgangs durchläuft die Transaktion verschiedene Zustände. Mit dem StatusRequest können Sie den aktuellen Status einer Transaktion abfragen. Die Statusmeldungen werden in Teil 2 dieses Handbuchs eingehend erläutert RefundRequest (Aufruf zur Rückbuchung) Mit dem RefundRequest buchen Sie zwischen 0 und 100 % einer bereits bestehenden Transaktion zurück. Sofern die Bezahlmethode dies unterstützt, können Sie die Rückzahlung auf die ursprünglich verwendete Bezahlmethode ausführen. Sie können auch mehrere RefundRequests auf eine einzelne Transaktion ausführen, vorausgesetzt, sie überschreiten in der Summe nicht den ursprünglichen Transaktionspreis. Zurückbuchungen sind endgültig, nicht stornierbar und bleiben selbst dann gültig, wenn die ursprüngliche Transaktion ausgebucht wird CancelRequest (Aufruf zur Stornierung) Mit dem CancelRequest führen Sie eine Stornierung durch. Hierdurch buchen Sie wahlweise 100 % des ursprünglichen Transaktionsbetrages auf das zur Einzahlung verwendete Zahlungsmittel des Kunden zurück oder stornieren eine mit dem Kunden abgeschlossene Zahlungsvereinbarung. Sie haben zudem die Möglichkeit sowohl die Transaktion als auch die Zahlungsvereinbarung in einem CancelRequest zu stornieren. Technisch gesehen handelt es sich beim Storno um eine Vollgutschrift. Stornierungen sind endgültig und können selbst nicht storniert werden CreditRequest (Aufruf zur Gutschrift) Der CreditRequest dient dazu, eine Gutschrift auszuführen. Sie können ohne Bezug zu einer vorherigen Transaktion eine Gutschrift oder eine Teilgutschrift auszahlen. Als Kundenreferenz dient hierfür wahlweise die Kundenreferenznummer oder die -Adresse, wobei es irrelevant ist, ob bereits ein ClickandBuy-Konto unter dieser -Adresse besteht oder nicht. Ist dies nicht der Fall, erhält der Kunde neben einer generellen Informationsmail genauere Anleitungen, wie er ein Endkundenkonto anlegen und die Gutschrift annehmen kann. Bei Gutschriften auf eine -Adresse hat der Kunde standardmässig 30 Tage Zeit die Gutschrift einzulösen, danach wird diese automatisch storniert. Gutschriften auf eine Kundenreferenznummer müssen vom Kunden nicht explizit eingelöst werden. Gutschriften sind endgültig und können nicht storniert werden. 29

30 TEIL 1 ALLGEMEINE ÜBERSICHT 3.4 Praktische Bedeutung der Batch Calls Sie können die fünf Bezahl-Transaktionen (PayRequest, PayRequestRecurring, CreditRequest, RefundRequest und CancelRequest (vgl. Abschnitt 3.3) sammeln, bevor Sie sie zur Ausführung an das ClickandBuy-System senden. Es stehen drei Batch Calls zur Verfügung, um einen Batch zu erstellen und auszuführen: Create Batch: Add Batch Item: Execute Batch: Batch (BatchID) anlegen Sie können einen der Transaction Calls (PayRequest, PayRequestRecurrent, CreditRequest, RefundRequest, CancelRequest) für die Stapelverarbeitung auswählen. Wählen Sie zum Beispiel den PayRequest, um eine Folge von einmaligen Bezahlvorgängen für verschiedene Kunden vorzubereiten. Oder wählen Sie den RefundRequest, wenn Sie eine Reihe von Rückerstattungen an Käufer eines bestimmten Produkts leisten möchten. ClickandBuy verarbeitet die im Batchjob enthaltene Folge von Anforderungen sequenziell. Ein Batchjob kann bis zu 128 Aktionen enthalten. Mit diesem Call starten Sie die Stapelverarbeitung. Zwei weitere Batch Calls vervollständigen die Batch-Funktionalität: Get Batch Status: Batchstatus anzeigen. Die Statusmeldungen werden in Teil 2 dieses Handbuchs eingehend erläutert. Cancel Batch: Batch löschen. Über die BatchID können Sie eine bestimmte vorbereitete Stapelverarbeitung löschen, sofern diese noch nicht ausgeführt wurde. 30

31 TEIL 1 ALLGEMEINE ÜBERSICHT 3.5 Praktische Bedeutung der Accounting Calls (Requests) Den Zugriff auf Abrechnungsdokumente realisiert der Accounting Call GetAccountingDocuments. Ihre E-Commerce-Anwendung nutzt den GetAccountingDocuments Call zum Beispiel für: den Import von Abrechnungsdokumenten in Ihre E-Commerce-Anwendung. den Rechte-basierten Zugriff auf Abrechnungsdokumente via URL für Ihre Mitarbeiter. den gezielten Abruf von Abrechnungsdokumenten aus den letzten 90 Tagen. 3.6 Der Merchant Messaging Service (MMS) Die Bezahlvorgänge durchlaufen von der ersten Anfrage bis zum Abschluss verschiedene Zustände (zum Beispiel CREATED, wenn die Transaktion angelegt ist, und SUCCESS, wenn ClickandBuy eine Zahlung prozessiert hat). Die API-Schnittstelle registriert jeden Status. Der Benachrichtigungsservice MMS (Merchant Messaging Service), der in der API angelegt ist, informiert Sie über jede Statusänderung. Es handelt sich um einen Push- Dienst, der die Nachrichten zeitnah an Ihr System übermittelt. Es ist dann keine aktive Nachfrage Ihrerseits mehr notwendig, um über den aktuellen Status einer Transaktion informiert zu werden. ClickandBuy hat diesen Benachrichtigungsdienst so eingerichtet, dass Ihr System nicht überschwemmt wird. Vielmehr entscheiden Sie selbst durch passende Abonnements der Systemmeldungen, von welchen Statusänderungen Sie informiert werden möchten und von welchen nicht. 31

32 : 32

33 4 Allgemeines Die Möglichkeiten der neuen API-Schnittstelle Die ClickandBuy-API bietet Ihnen die besten Voraussetzungen, um Ihr E-Commerce- System unkompliziert anzubinden. Wie in den vorangegangen Kapiteln erläutert, werden alle Geschäftsmodelle von der ClickandBuy-API erfasst. Sie benötigen nur wenige API-Calls, um die verschiedenen Bezahlvorgänge schnell und sicher zu realisieren. Inhalt der API-Referenz Das hier vorliegende Kapitel gibt Ihnen als Entwickler oder Techniker im E- Commerce-System einen Überblick über die Grundfunktionen der neuen ClickandBuy-Transaktionsschnittstelle. Dabei ist zu beachten, dass das System aktuell in kurzen Zyklen und großen Schritten weiterentwickelt wird. Die vorliegende Dokumentation wird daher kontinuierlich weiter gepflegt. Mit dieser technischen Dokumentation erhalten Sie das erste Handwerkszeug zur Einbindung der ClickandBuy Universal Payment API in Ihre E-Commerce-Anwendung. Als zusätzliche Unterstützung stehen Ihnen umfangreiche Beispielskripte sowie unser Developers Forum unter zur Verfügung. Selbstverständlich steht Ihnen zudem bei allen aufkommenden Fragen unser Team hilfreich zur Seite. Der Einfachheit halber nennen wir das ClickandBuy-System an vielen Stellen nur API. Gestaltungsmerkmale in diesem Kapitel Bestimmte Textelemente sind in diesem Kapitel folgendermaßen ausgezeichnet: Beispiel der Textauszeichung Request, Response <merchantid> PAYMENT_PENDING Bedeutung Englischer Begriff als Teil API-Fachsprache XML-Tag URL Status 33

34 Symbole in den Diagrammen Das vorliegende Kapitel enthält Ablaufdiagramme in den Abschnitten Die Prozesse und Die Status in den Transaktionen. Die Symbole haben folgende Bedeutungen: Symbol Bedeutung Prozessstart Prozessende Call Aktion Status Entscheidung OK Not OK (NOK) Planmäßiger Schritt Optionaler Schritt Erfolgreicher Schritt Erfolgloser Schritt Fakultativ 34

35 5 Grundlegendes in der Übersicht Dieser Abschnitt beschreibt die wichtigsten Voraussetzungen für die technische Anbindung der E-Commerce-Anwendung an ClickandBuy. 5.1 Protokolle und Referenz-URLs XML und SOAP Die ClickandBuy Universal Payment API basiert auf XML-Webservice. Um eine Kommunikation mit ClickandBuy herzustellen, benötigen Sie das Standard- Webprotokoll SOAP (Simple Object Access Protocol). WSDL Die genaue Beschreibung der API ist in der WSDL (Web Services Description Language) enthalten, die Sie über die folgende URL beziehen können: XSD: Benötigte Referenzen in der Übersicht Mit den im Folgenden zitierten XML-Schema-Definitionen (XSDs) erhalten Sie alle Quellen auf einen Blick. Die referenzierten URLs lauten: Siehe auch ab Seite 68. Siehe auch ab Seite Siehe auch ab Seite Siehe auch ab Seite 94. Endpoint: Für das erfolgreiche Absetzen eines Requests müssen Sie auf die Einhaltung der per WSDL definierten Struktur achten. Verwenden Sie die Zeichenkodierung UTF-8 für das Encoding. 35

36 5.2 Testumgebung ( Sandbox ) Falls Sie in der ClickandBuy-Testumgebung, d. h. auf dem Staging System (auch Sandbox genannt) entwickeln möchten, lautet die Domain in den URLs, die auf das Staging System zeigen: clickandbuy-s1.com. Die Domain clickandbuy.com ist die echte Umgebung, in der nur Transaktionen mit Echtgeld ausgeführt werden. 5.3 Erläuterungen zur Authentifikation Wie Sie der WSDL entnehmen können, enthält jeder Request an die API einen Teil <authentication>. Das darin enthaltene Element <token> enthält einen Hash, der in einer bestimmten Form von Ihnen generiert werden muss. ClickandBuy erstellt den gleichen Hash und vergleicht beide. Unterscheiden sie sich, wird der Request mit einer entsprechenden Fehlermeldung aus Sicherheitsgründen abgewiesen. Beispiel für eine Anfrage: <authentication> <merchantid>4000</merchantid> <projectid>1</projectid> <token> ::c48bb9e02e6dd44fa402eb412a851ad8f 3C488A0</token> </authentication> Die Elemente weisen das jeweils referenzierte Projekt (<projectid>) eines eindeutigen Anbieterkontos (<merchantid>) aus. Das Element <token> validiert die Berechtigung der Anfrage. Es hat den Aufbau: <timestamp>::<hex(sha1)-hash des strings [projectid]::[secretkey]::[timestamp] > wobei gilt: <merchantid> (wird in Ihrem Anbieterkonto oben rechts angezeigt); <projectid> (eindeutige ID: wird in Ihrem Anbieterkonto unter Settlement Account und bestehendes Projekt angezeigt); <secretkey> (eindeutiger Schlüssel: wird in Ihrem Anbieterkonto unter den bestehenden Settlement Account und Projekt angezeigt); <timestamp> (hat das Format: YYYYMMDDhhmmss und muss in UTC sein). 36

37 Beispiel eines Code-Skripts in Pseudocode -Notation: function createtoken Get Timestamp; Get projectid; Get secretkey; HashString="projectID::secretKey::timestamp ; token=timestamp."::".hex(sha1(hashstring)) return Token; end createtoken; // Konkrete Werte sharedsecret 1::sharedSecret:: ::37d9e3 f3452a863fb36d16dcdd a2ef 37

38 6 Die Prozesse Die Transaktionslogik von ClickandBuy unterscheidet drei grundlegende Prozesse: den einfachen Bezahlprozess die initiale Autorisierung und wiederkehrende Zahlungen den Batchprozess. Calls und Prozesse Ihr E-Commerce-System realisiert diese Prozesse mithilfe der zwölf Calls. Diese werden unter technischem Aspekt ab Seite 42 beschrieben. 6.1 Der einfache Bezahlprozess Der Bezahlprozess besteht aus zwei grundlegenden Schritten: 1. Anlegen der Transaktion durch Übermittlung der relevanten Warenkorbdetails an ClickandBuy durch den Call PayRequest. Als Antwort erhält der Shop den Bezahl- Link. 2. Weiterleitung des Kunden auf den Bezahl-Link auf der Checkout-Seite, Authentifizierung des ClickandBuy-Nutzers mittels Login/Registrierung, Zahlung der Verbindlichkeit durch die bevorzugte Zahlungsmethode, Bestätigung der Transaktion und Rückleitung des Kunden auf die Bestätigungsseite (Merchant Landing Page) im Shop. Das nachfolgende Diagramm illustriert in vereinfachter Form den Ablauf des einfachen Bezahlprozesses: 38

39 6.2 Initiale Autorisierung und wiederkehrende Zahlungen Der Prozess der initialen Autorisierung für wiederkehrende Zahlungen ist grundsätzlich der gleiche wie beim einfachen Bezahlprozess (siehe vorangegangener Abschnitt). Lediglich einige API-Parameter unterscheiden die beiden Prozesse. Für den Prozess der initalen Autorisierung legt ClickandBuy im PayRequest eine RecurringPaymentAuthorization (RPA) im Backend an. Durch die initiale Autorisierung geht der Kunde ein Billing Agreement mit Ihnen ein. Mithilfe des Billing Agreements können Sie zu einem späteren Zeitpunkt weitere Zahlungen anstoßen, ohne eine erneute Interaktion zur Autorisierung durch den Kunden zu benötigen. Hierzu verwenden Sie den Call PayRequestRecurring. 39

40 6.3 Der Batchprozess Um Requests verschiedener Art zunächst anzusammeln, bevor diese sequenziell durch ClickandBuy verarbeitet werden, können Sie den Batchprozess verwenden. Dieser gliedert sich in drei Abschnitte: 1. Anlegen eines Batchjobs 2. Hinzufügen einzelner Batchitems (Transaktionen) 3. Schließen bzw. Starten des Batchjobs. Nach dem Starten des Batchjobs prozessiert ClickandBuy die einzelnen Items (das heißt die einzelnen Requests) der Reihe nach. Die Bearbeitungszeit kann je nach Auslastung des Systems und Größe bzw. Umfang des Batchjobs variieren. Das nachfolgende Diagramm illustriert den Gesamtablauf des Batchprozesses: 40

41 Der Teilprozess 2 Hinzufügen einzelner Batchitems (additem) ist im nachstehenden Diagramm skizziert: 6.4 Sonderfall der Bezahlart: Vorkasse Die Bezahlart Vorkasse stellt eine Sonderfunktion unter den Bezahlarten dar. Der Kunde kann im regulären Bezahlprozess auf der ClickandBuy-Checkout-Seite die Variante Vorkasse auswählen, wenn er weder eine Bankverbindung noch eine Kreditkarte nutzen will. Der Kunde muss dann in einem zweiten Schritt eine Überweisung auf sein ClickandBuy-Konto vornehmen. Der Transaktionsstatus bleibt bis zum Geldeingang im Status IN_PROGRESS. Nach Eingang der Überweisung, wenn ClickandBuy einen Zahlungseingang festgestellt hat, wechselt der Transaktionsstatus dann auf SUCCESS oder PAYMENT_GUARANTEE. Im Geschäftsmodell Abonnement ist keine Vorkasse möglich. Außerdem muss der Status SUCCESS_EXPIRATION auf >1440 Minuten (>24h) und weniger als 30 Tage gestellt sein. Zur Bedeutung der Transaktionsstatus siehe auch den Abschnitt Die Status in den Transaktionen ; Seite

42 7 Die Calls (Aufrufe) Das ClickandBuy-System bietet mit zwölf Calls diverse Anwendungsmöglichkeiten bzw. Modelle von Geschäftsprozessen. Hierunter fallen unter anderem: die Abwicklung von Einzeltransaktionen die Abwicklung von zeitlich oder monetär begrenzten Abonnements die Abwicklung von Teilzahlungen die Abwicklung von Ratenzahlungen die Abwicklung von Gutschriften auf eine -Adresse oder Kundenreferenznummer Teilgutschriften auf eine bereits abgewickelte Transaktion Sornierung einer Transaktion, Zahlungsvereinbarung oder beidem der Abruf von Abrechnungsdokumenten. Zuordnung von Geschäftsprozessen zu Calls Geschäftsprozesse Zahlungsrelevante Modelle Rückabwicklungen Abfrage eines Transaktionsstatus Bündelung der Requests in Batch Calls Abruf von Abrechnungsdokumenten Calls PayRequest PayRequestRecurring CreditRequest, RefundRequest CancelRequest StatusRequest CreateBatch AddBatchItem ExecuteBatch GetBatchStatus CancelBatch GetAccountingDocuments Zu den Ein- und Ausgabeparametern der Calls In diesem Abschnitt beschreiben wir die zwölf Calls mit ihren Ein- und Ausgabeparametern. Die weiteren Call-spezifischen Parameter und dazu gehörenden Typen sowie die zu den Typen gehörenden Datenfelder sind im folgenden Abschnitt Die XML-Schema-Definitionen (XSDs) alphabetisch aufgelistet. 42

43 7.1 PayRequest (Einzeltransaktion mit Kundeninteraktion) Der Call PayRequest ist der einzige Call, der einen Onlineprozess anstößt, da er die Interaktion des Kunden bedingt. Die Response eines PayRequests ist unter anderem eine TransactionID und eine URL, auf die der Kunde zur Transaktionsbestätigung und Zahlungsinitiierung geleitet werden muss ( RedirectURL ). Ebenfalls wird z. B. der Status mit zurückgeliefert. Der PayRequest kann zu zwei Zwecken verwendet werden: 1. um eine Einzeltransaktion anzulegen 2. um eine RecurringPaymentAuthorization für wiederkehrende Zahlungen zu initiieren. Zur näheren Erläuterung dieser Anwendungen siehe auch die Abschnitte 6.1 und 6.2, Seite 38 und 39. Zum Call PayRequest gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input payrequest_request cab:payrequest_request Output payrequest_response cab:payrequest_response Exception errordetails cab:errordetails 7.2 PayRequestRecurring (Einzeltransaktion ohne Kundeninteraktion) Wurde im Vorfeld mittels entsprechender Parameterübergabe im PayRequest eine RecurringPaymentAuthorization (RPA) angelegt und autorisiert, kann in einem zweiten Schritt mittels des Calls PayRequestRecurring eine Einzeltransaktion auf die RPA angestoßen werden. Beachten Sie, dass zwingend eine RPA angelegt und im Status AUTHORIZED sein muss, bevor Sie einen PayRequestRecurring absetzen können. Der Initialisierungscall (PayRequest) kann bereits eine erste Debitierung enthalten (ansonsten gilt der Parameter: <amount=0>). Dies ermöglicht Ihnen den sofortigen Einzug der ersten Rate und spart so eine weitere Anfrage ein. Die Antwort des ClickandBuy-Systems beinhaltet analog zur PayRequest_Response neben der TransactionID einen aktuellen Status der Transaktion. Zur näheren Erläuterung dieser Anwendung siehe auch den Abschnitt 6.2, Seite

44 Zum Call PayRequestRecurring gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input payrequestrecurring_request cab:payrequestrecurring_request Output payrequestrecurring_response cab:payrequestrecurring_response Exception errordetails cab:errordetails 7.3 RefundRequest (Aufruf zur Rückbuchung) Der Call RefundRequest ermöglicht Ihnen, zwischen 0 und 100 % einer bereits bestehenden Transaktion auf die ursprünglich verwendete Bezahlmethode zurückzubuchen, sofern dies von der Bezahlmethode unterstützt wird. Ist dies nicht der Fall, erhält der Kunde den Betrag auf sein E-Geldkonto gutgeschrieben. Sie können mehrere Refunds auf eine einzelne Transaktion ausführen, vorausgesetzt, Sie überschreiten in der Summe nicht den ursprünglichen Transaktionspreis. ClickandBuy antwortet im Erfolgsfall mit der TransactionID und dem Status derselben. Refunds sind endgültig, nicht stornierbar und bleiben selbst dann gültig, wenn die ursprüngliche Transaktion ausgebucht wird. Zum Call RefundRequest gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input refundrequest_request cab:refundrequest_request Output refundrequest_response cab:refundrequest_response Exception errordetails cab:errordetails 7.4 CancelRequest (Aufruf zur Stornierung) Um eine Transaktion zu stornieren, können Sie den Call CancelRequest verwenden. Dies ist nur bei einem der folgenden Status möglich: IN_PROGRESS, SUCCESS, PAYMENT_GUARANTEE und PAYMENT_PENDING. Nähere Informationen zu den verschiedenen Status entnehmen Sie bitte dem Abschnitt Die Status in den Transaktionen, Seite 98. Durch einen CancelRequest werden 100 % des ursprünglichen Transaktionsbetrags auf die Hauptbezahlmethode des Kunden zurückgebucht, sofern dies die Bezahlmethode unterstützt. Sie können den CancelRequest auch dazu nutzen eine Zahlungsvereinbarung zu stornieren oder die initiale Transaktion zusammen mit der Zahlungsvereinbarung in einem Aufruf zu stornieren. Die Antwort des ClickandBuy-Systems enthält neben der TransactionID auch den neuen Status der Transaktion. 44

45 Stornierungen sind nicht möglich, wenn eine Transaktion schon zum Teil zurück gebucht wurde (Refund). Der restliche Betrag muss dann ebenfalls über Refund zurückgebucht werden. Stornierungen sind endgültig und können selbst nicht storniert werden. Zum Call CancelRequest gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input cancelrequest_request cab:cancelrequest_request Output cancelrequest_response cab:cancelrequest_response Exception errordetails cab:errordetails 7.5 CreditRequest (Aufruf zur Gutschrift) Eine Gutschrift ohne Bezug zu einer vorherigen Transaktion können Sie durch den Call CreditRequest ausführen. Als Kundenreferenz dient hierfür wahlweise die Kundenreferenznummer oder die -Adresse, wobei es irrelevant ist, ob bereits ein ClickandBuy-Konto unter dieser -Adresse besteht oder nicht. Ist dies nicht der Fall erhält der Kunde neben einer Informationsmail eine Anleitung, wie er ein Kundenkonto anlegen und die Gutschrift annehmen kann. Bei Gutschriften auf eine E- Mail-Adresse hat der Kunde standardmässig 30 Tage Zeit diese einzulösen, danach wird die Gutschrift automatisch storniert. Gutschriften auf eine Kundenreferenznummer müssen vom Kunden nicht explizit eingelöst werden. Die Antwort des ClickandBuy-Systems enthält neben der TransactionID auch einen Status, der über die erfolgreiche Gutschrift informiert. Gutschriften, welche bereits vom Kunden eingelöst wurden sind endgültig und können nicht storniert werden. Zum Call CeditRequest gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input creditrequest_request cab:creditrequest_request Output creditrequest_response cab:creditrequest_response Exception errordetails cab:errordetails 45

46 7.6 StatusRequest (Abfrage des Transaktionsstatus) Sie haben die Möglichkeit, über den Call StatusRequest zu jedem Zeitpunkt den Status einer Transaktion abzufragen. Nähere Informationen zu den verschiedenen Status entnehmen Sie bitte dem Abschnitt Die Status in den Transaktionen, Seite 98. Zum Call StatusRequest gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input statusrequest_request cab:statusrequest_request Output statusrequest_response cab:statusrequest_response Exception errordetails cab:errordetails 7.7 CreateBatch (Stapelverabeitung) Um einen Batchjob zu starten, verwenden Sie den Call CreateBatch. ClickandBuy antwortet mit der entsprechenden BatchID sowie dem Status. Zum Call CreateBatch gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input createbatch_request cab:createbatch_request Output createbatch_response cab:createbatch_response Exception errordetails cab:errordetails 46

47 7.8 AddBatchItem (Stapeldatei füllen) Einem bereits bestehenden Batchjob müssen einzelne Items (= Transaktionen) hinzugefügt werden. Für das Hinzufügen eines Items verwenden Sie den Call AddBatchItem. Um einem Batch Items hinzufügen zu können, darf dieser noch nicht geschlossen bzw. gestartet worden sein (vgl. Abschnitt 47

48 Der Batchprozess, Seite 40). ClickandBuy antwortet mit der entsprechenden BatchID sowie dem Status. Für jedes zugefügte Item wird eine BatchItem-Info mit ID und Status oder bei Nichterfolg ErrorDetails zurückgegeben. Zum Call AddBatchItem gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input addbatchitem_request cab:addbatchitem_request Output addbatchitem_response cab:addbatchitem_response Exception errordetails cab:errordetails 7.9 ExecuteBatch (Stapelverabeitung starten) Sind dem Batchjob alle Items hinzugefügt worden, muss dieser durch den Call ExecuteBatch gestartet werden. ClickandBuy arbeitet dann den Batchjob asynchron ab. Ein nachträgliches Hinzufügen von Items ist nach dem Start nicht mehr möglich. Die Response enthält neben der BatchID den jeweiligen Status. Zum Call ExecuteBatch gehören folgende Ein- und Ausgabeparameter. Parameter Name Beschreibung Input executebatch_request cab:executebatch_request Output executebatch_response cab:executebatch_response Exception errordetails cab:errordetails 48

49 7.10 GetBatchStatus (Statusabfrage der Stapelverabeitung) Um den aktuellen Status eines Batchjobs bzw. der enthaltenen Items abzufragen, verwenden Sie den Call GetBatchStatus. ClickandBuy antwortet mit der jeweiligen BatchID sowie dem Status bzw. mit den einzelnen Items nebst deren Status. Zum Call GetBatchStatus gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input getbatchstatus_request cab:getbatchstatus_request Output getbatchstatus_response cab:getbatchstatus_response Exception errordetails cab:errordetails 7.11 CancelBatch (Stapelverabeitungsdatei verwerfen) Ein Batchjob kann nur dann storniert werden, wenn er im Status CREATED (vgl. Seite 98) ist. Dies bedeutet im Umkehrschluss, dass ein bereits gestarteter Batch nicht gestoppt werden kann. Die Response enthält neben der BatchID auch den aktuellen Status. Zum Call CancelBatch gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input cancelbatch_request cab:cancelbatch_request Output cancelbatch_response cab:cancelbatch_response Exception errordetails cab:errordetails 49

50 7.12 GetAccountingDocuments (Abruf von Abrechnungsdokumenten) Mit Hilfe des Calls GetAccountingDocuments können Sie auf Ihre Abrechnungsdokumente zugreifen. Die Response enthält eine Struktur welche neben der Liste der Abrechnungsdokumente auch einen Link für den direkten Download, als auch für den Zugriff über den Servicebereich beinhaltet. Zum Call GetAccountingDocuments gehören folgende Ein- und Ausgabeparameter: Parameter Name Beschreibung Input Output getaccountingdocuments_reque st getaccountingdocuments_respo nse Exception errordetails cab:errordetails cab:getaccountingdocuments_request cab:getaccountingdocuments_response 50

51 8 Schnelleinstieg Implementierung Wenn Sie sich als Händler bei ClickandBuy registrieren möchten, empfehlen wir Ihnen: 1. Überlegen Sie, welche Geschäftsmodelle (vgl. ab Seite 12) Sie benötigen und abrechnen möchten. 2. Implementieren Sie den Merchant Messaging Service (vgl. nächstes Kapitel ab Seite 65). Dieser Benachrichtigungsservice ist unentbehrlich zur Nachverfolgung der Transaktionen. Auf den nächsten Seiten beschreiben wir, wie Sie die typischen Bezahlvorgänge schnell und unkompliziert mit Ihrem System ausführen. Für die gängigen Geschäftsmodelle benötigen Sie nur wenig Aufwand. Um z. B einen Warenkorb abzurechnen, reicht ein einziger Aufruf (Call). Die zitierten Calls, Typen und Parameter sind im Kapitel Die XML- Schema-Definitionen (XSDs) ab Seite 68 detailliert aufgeführt. Dort finden Sie die gesamten Funktionalitäten des ClickandBuy- Systems. 51

52 8.1 Warenkorb in Rechnung stellen Der Warenkorb entspricht dem Modell der Einmalzahlung mit und ohne Vorkasse. 1. Initialisierung des ClickandBuy-Systems Generieren Sie einen PayRequest Verwenden Sie aus den PayRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) folgende Pflichtparameter: Typ Parameter Erläuterung PayRequestDetails amount Der Parameter amount ist ein zusammengesetzter Datentyp und umfasst neben dem eigentlichen Betrag auch die Währung. Mit dieser einfachen Angabe ist die Transaktion PayRequest möglich. Sollte in Ihrem Vertrag mit ClickandBuy Verkäuferschutz enthalten sein, sind immer auch die Adressdaten des Kunden (s. u.) zu übergeben. Verwenden Sie zusätzlich mindestens folgende Parameter des Typs PayRequestDetails: Parameter API-Beschreibung Erläuterungen billing Rechnungsempfänger Zusammengesetzter Datentyp der die vollständige Rechnungsadresse des Kundenvorgangs beinhaltet. shipping Lieferungsempfänger Zusammengesetzter Datentyp der die vollständige Lieferungsadresse des Kundenvorgangs beinhaltet. consumerlanguage consumercountry successurl Die Sprache, in der die folgenden Bezahlseiten angezeigt werden. Das Land, das auf den folgenden Bezahlseiten vorausgewählt ist. URL ( oder auf die der Kunde im Erfolgsfall geleitet wird. Ohne diese Angabe werden dem Kunden die ClickandBuy-Seiten in Englisch angezeigt. 52

53 failureurl URL ( oder auf die der Kunde im Nichterfolgsfall geleitet wird. orderdetails Details zur Bestellung, z. B. Bezeichnungen der einzelnen Posten. OrderDetailItem successexpiration Ein Subtyp der orderdetails, siehe Seite 75. Lebensdauer des PayRequests. Nach Ablauf wird der Status auf EXPIRED gesetzt. Wenn kein Text übergeben wird, wird Ihr Standardtext aus dem Projekt oder der ClickandBuy- Standardtext angezeigt. Für den Sonderfall Vorkasse muss die successexpiration auf >=1440 Minuten (>=24h) stehen. Bei einem Wert <24h wird keine Vorkasse angezeigt. 2. Antworten von ClickandBuy Nach Empfang des Calls PayRequests reagiert ClickandBuy folgendermaßen: Gibt eine TransactionID zurück. Speichern Sie die TransactionID in Ihrem System. Ohne diese ID können Sie den Vorgang für eventuelle spätere Schritte nicht identifizieren. Gibt im Erfolgsfall die redirecturl bzw. im Nichterfolgsfall die eine failureurl sowie die errordetails (vgl. Seite Fehler! Textmarke nicht definiert.) zurück. Leitet den Kunden weiter zur übergebenen redirecturl. Leitet den Kunden nach Abschluss des Vorgangs auf ClickandBuy-Seite auf die successurl bzw. failureurl, sofern diese übergeben wurden. Wenn keine URL übergeben wurde, wird die Einstellung aus Ihrem Projekt übernommen oder eine Default-URL von ClickandBuy verwendet. Wenn keine URL übergeben wurde, wird die Einstellung aus Ihrem Projekt übernommen oder eine Default-URL von ClickandBuy verwendet. 3. Weitere Maßnahmen des E-Commerce-Systems Wenn Ihr System die successurl erhalten hat, fragen Sie den Status der Transaktion ab, indem Sie den StatusRequest auslösen. 53

54 8.2 Wiederkehrende Zahlung Mit wiederkehrenden Zahlungen können Sie die Geschäftsvorfälle der Billing- Agreement-Modelle (z. B. Abonnement, Teillieferung, Ratenzahlungen, Sofortkauf und Micropayment abbilden): Für die wiederkehrende Zahlung benötigt ClickandBuy ein Zahlungsmittel, das ohne weitere Kundeninteraktion belastet werden kann. Deshalb bietet ClickandBuy hierfür das Lastschriftverfahren und Kreditkarten als Zahlungsmittel an. Im Folgenden beschreiben wir, wie Sie die wiederkehrende Zahlung nach erfolgtem PayRequest und RPA (Recurring Payment Authorization). (vgl. u. a. Seite 39) durchführen. 1. Aufrufe des E-Commerce-Systems für die Initialzahlung Generieren Sie einen Call PayRequest und senden Sie ihn an ClickandBuy. Verwenden Sie mindestens folgende Pflichtparameter: Typ Parameter Erläuterung PayRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) amount Betrag der Initialzahlung. Die Initialzahlung sollte 0 betragen. Mit der Initialzahlung wird die Währung für alle folgenden Abbuchungen festgelegt (auch wenn der Wert 0 beträgt). PayRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) createrecurring Struktur für das Anlegen einer RPA (RecurringPaymentAuthorization). RecurringPayment Authorization (vgl. Seite Fehler! Textmarke nicht definiert.) description Dieser Beschreibungstext wird dem Kunden in seinem ClickandBuy-Kundenbereich angezeigt. Wie bei der Warenkorbzahlung gilt: Sollte in Ihrem Vertrag mit ClickandBuy Verkäuferschutz enthalten sein, sind auch die Adressdaten des Kunden zu übergeben. 54

55 Verwenden Sie zusätzlich optionale Parameter der Typen PayRequesDetails, PayRequestRecurringDetails und RecurringPaymentAuthorization, um verschiedene Geschäftsmodelle (in der folgenden Tabelle fett gestellt) zu realisieren: Typ Parameter API-Beschreibung Erläuterungen PayRequest Recurring Details (vgl. Seite Fehler! Textmarke nicht definiert.) billing Rechnungsempfänger Diese Adressen werden bei shipping Lieferungsempfänger Neuanmeldung zum Vorausfüllen der Kundendaten auf CAB Seite genutzt und müssen im Rahmen des Verkäuferschutzes vollständig übergeben werden. PayRequest Details (vgl. Seite Fehler! Textmarke nicht definiert.) Consumer Language Consumer Country successurl Die Sprache, in der die folgenden Bezahlseiten angezeigt werden. Das Land, das auf den folgenden Bezahlseiten vorausgewählt ist. URL, auf die der Kunde im Erfolgsfall geleitet wird. Als Default werden dem Kunden die Bezahlseiten in Englisch angezeigt. failureurl URL, auf die der Kunde im Nichterfolgsfall geleitet wird. Recurring Payment Authorization (vgl. Seite Fehler! Textmarke nicht definiert.) numberlimit amountlimit Die maximale Anzahl von Zahlungen, die über diese RPA angestoßen werden können. Der maximale Betrag, der über diese RPA abgerechnet werden kann. Die Parameter numberlimit und amountlimit werden für Teillieferungen benötigt. Sie können jederzeit bis zum gesetzten Limit abbuchen oder belasten. Bis zum Erreichen des amountlimits können Sie bei Teilzahlungen jederzeit die gewünschte Rate abbuchen. expiredate Ablaufdatum der RPA. Anwendbar z. B. für Abonnement revokableby Consumer Gibt an, ob eine RPA vom Kunden widerrufen werden kann. Beim Sofortkauf sollte dieser Parameter auf true gesetzt sein, damit der Kunde widerrufen kann. 55

56 Um Ihren Stammkunden entgegenzukommen, können Sie selbst entscheiden, ob Sie die Ware schon vor Eintreffen der Statusmeldung SUCCESS (d. h. vor Inkrafttreten des Verkäuferschutzes) versenden. 2. Antworten von ClickandBuy Nach Empfang des ersten Calls PayRequests reagiert ClickandBuy folgendermaßen: Gibt eine TransactionID zurück. Speichern Sie die TransactionID. Ohne diese ID können Sie den Vorgang für eventuelle spätere Schritte nicht identifizieren. Gibt eine recurringpayment AuthorisationID zurück. Die recurringpaymentauthorisationid ist die Referenz für jede weitere Abbuchung. Sie muss ClickandBuy bei jeder folgenden Abbuchung übergeben werden. Gibt im Nichterfolgsfall die errordetails (vgl. Seite Fehler! Textmarke nicht definiert.) zurück. 3. Aufruf des E-Commerce-Systems für die weiteren Zahlungen Generieren Sie einen Call PayRequestRecurring (vgl. Seite Fehler! Textmarke nicht definiert.) und senden Sie ihn an ClickandBuy. Verwenden Sie mindestens folgende Pflichtparameter: Typ Parameter Erläuterung PayRequest RecurringDetails (vgl. Seite Fehler! Textmarke nicht definiert.) amount recurringpayment AuthorisationID Betrag und Währung der Folgezahlung. ID der RPA. 56

57 4. Antworten von ClickandBuy Nach Empfang eines weiteren PayRequestRecurring reagiert ClickandBuy folgendermaßen: Gibt den TransactionIDStatus (vgl. Seite Fehler! Textmarke nicht definiert.) zurück. Gibt im Nichterfolgsfall die errordetails (vgl. Seite Fehler! Textmarke nicht definiert.) zurück. Eine redirecturl wird hier nicht benötigt. Um sich über den Erfolg der Transaktion zu informieren, stehen die TransactionID und der TransactionStatus zur Verfügung. Sollte bei einer Anfrage die Zahlung nicht möglich sein, wird ClickandBuy den Kunden per und in seinem Kundenbereich über offene Posten informieren. 57

58 8.3 Sammeln/Stapelverarbeitung Um Transaktionen wie z. B. Micropayments gesammelt einzureichen, nutzen Sie die Stapelverarbeitung in Batch-Dateien. 1. Aufruf des E-Commerce-Systems zum Anlegen eines Batch Generieren Sie den Call CreateBatch und senden Sie ihn an ClickandBuy. Verwenden Sie mindestens folgende Pflichtparameter: Typ Parameter API-Beschreibung CreateBatch_Request (vgl. Seite Fehler! Textmarke nicht definiert.) authentification details Struktur mit Details zur API- Authentifizierung. Struktur für CreateBatchRequest_Details. Verwenden Sie optional den zusätzlichen Parameter: Typ Parameter API-Beschreibung CreateBatchDetails (vgl. Seite Fehler! Textmarke nicht definiert.) ExternalBatchID Externe ID des Batchs aus dem Anbietersystem. Falls Sie die Stapelverabeitung wieder löschen möchten, verwenden Sie den Call CancelBatch_Request (vgl. Seite Fehler! Textmarke nicht definiert.). 2. Antworten von ClickandBuy Nach Empfang des Calls CreateBatch reagiert ClickandBuy folgendermaßen: Gibt einen BatchIDStatus (vgl. Seite Fehler! Textmarke nicht definiert.) zurück. Mit dem BatchIDStatus erhalten Sie mindestens die BatchID. Speichern Sie die BatchID. Die ClickandBuy-eigene BatchID wird bei jedem Hinzufügen von Buchungen für den jeweiligen Batch benötigt. Falls beim Aufruf angefordert, erhalten Sie auch Ihre optionale Batch-ID Mit der Rückgabe BatchIDStatus ist der Datencontainer für die Stapelverarbeitung angelegt. Sie können ihn jetzt mit Buchungen füllen. 58

59 3. Aufrufe des E-Commerce-Systems zum Füllen eines Batch Generieren Sie einen Call AddBatchItem (vgl. Seite Fehler! Textmarke nicht definiert.) und senden Sie ihn an ClickandBuy. Nutzen Sie folgende Parameter: Typ Parameter Erläuterung AddBatchItem ProcessingDetails (vgl. Seite Fehler! Textmarke nicht definiert.) payrequestdetails payrequestrecurring Details refundrequestdetails creditrequestdetails cancelrequestdetails Die Struktur der Requests für den Batch entspricht der Struktur der Requests im Warenkorb-Modell (siehe oben). Sie können pro Call bis zu 128 BatchItems zufügen; d. h., es können bis zu 128 Buchungen in der Stapelverarbeitung enthalten sein. Der Datentyp addbatchitemdetails umfasst zusätzlich die batchid, ohne die eine Zuordnung zu einem bestimmten Batch nicht möglich ist. Führen Sie den Call AddBatchItem_Request mehrmals aus, um den Batch mit Buchungen zu befüllen. Um die Stapeldatei zur Ausführung an ClickandBuy zu senden, generieren Sie einen Call ExecuteBatch (vgl. Seite Fehler! Textmarke nicht definiert.). Mit diesem Call schließen Sie die Batchdatei und geben sie im ClickandBuy-System in die Queue zur Ausführung. 4. Antworten von ClickandBuy Nach Empfang des Calls ExecuteBatch reagiert ClickandBuy folgendermaßen: Gibt einen BatchIDStatus (vgl. Seite Fehler! Textmarke nicht definiert.) zurück. Bei störungsfreiem Ablauf durchläuft der Batch die Status PENDING_EXECUTION und EXECUTED. Sie werden über einen asynchronen MMS-Event von jeder Buchung in der Stapelverarbeitung benachrichtigt. 59

60 8.4 Digitale Güter Entscheiden Sie bei der Abrechnung von digitalen Gütern (Downloads), mit welchem Geschäftsmodell Sie abrechnen möchten: Als Warenkorbmodell (vgl. oben, Seite 14) In einer Stapelverabeitung. In diesem Fall muss der Kunde zunächst mit einem Billing Agreement einmalig seine Einwilligung zu wiederholten Abbuchungen gegeben haben. Danach liefern Sie aus und buchen später ab. Entscheiden Sie außerdem, ob Sie den Content sofort nach Bezahlung ausliefern möchten oder ob Sie ihn erst später (mit Zeitverzug) zum Download bereitstellen möchten. Hierbei ist Folgendes zu bedenken: Auslieferung mit Zeitverzug Setzen Sie hierfür den Parameter successexpiration aus dem Call PayRequestDetails auf mindestens 30 Minuten. Auslieferung sofort nach Bezahlung Sollte die Ausfallrate von geringer Bedeutung sein, kann der Content ab dem Status SUCCESS ausgeliefert werden. Vorkasse Wenn Sie eine Vorkasse-Möglichkeit schaffen möchten, setzen Sie den Parameter successexpiration aus dem Call PayRequestDetails auf einen Wert >1440 Minuten (>24h). Bei einem Wert <24h erscheint keine Vorkasse. 60

61 8.5 Rückabwicklungen Sie können drei Arten von Rückabwicklungen ausführen: Die Rückerstattung ( Refund ) Die Stornierung ( Cancel ) Gutschriften ( Credit ) Allgemein gilt: Wenn auf Ihrem Konto keine Deckung für eine Rückabwicklung vorhanden ist, wird diese vom ClickandBuy-System abgelehnt. Es ist empfehlenswert, genug Geld auf dem Konto zu belassen, um Rückerstattungen auch nach der Abrechnungsperiode durchführen zu können. Mehrere Rückabwicklungen können in der Stapelverarbeitung auch gesammelt ausgeführt werden. Die Rückerstattung ist ein größeres Risiko als ein Storno, da z. B. eine von Ihnen durchgeführte und schon rückerstattete Lastschrift vom Kunden bei seiner Bank innerhalb von 6 Wochen nochmals per Widerspruch komplett zurückgebucht werden kann. Sobald es für eine Transaktion eine Rückerstattung gab, ist diese Transaktion nicht mehr stornierbar. Man kann nur noch den Restwert der Transaktion rückerstatten. 61

62 8.5.1 Rückerstattung 1. Aufruf des E-Commerce-Systems für die Rückerstattung Generieren Sie einen Call RefundRequest und senden Sie ihn an ClickandBuy. Verwenden Sie mindestens folgende Pflichtparameter: Typ Parameter Erläuterung RefundRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) amount transactionid Betrag und Währung der Anfrage. Bei wiederholten Zahlungen kann nicht mehr als der Einzelbetrag von jeder Transaktion erstattet werden. Wurden z. B. 100-Euro-Raten bezahlt, kann nicht mehr als 100 Euro pro Transaktion erstattet werden. TransactionID der ursprünglichen PayTransaction. Verwenden Sie optional die zusätzlichen Parameter: Typ Parameter API-Beschreibung RefundRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) orderdetails externalid Text, der dem Kunden für die Rückerstattung im Kundenbereich von ClickandBuy und in der - Kommunikation angezeigt wird. ID Ihres Systems. Wir empfehlen, immer eine eigene externalid beim RefundRequest mitzugeben, um doppelte Buchungen zu vermeiden. Sollte der Kommunikationsweg für die Rückantwort in irgendeiner Weise gestört sein, wird das ClickandBuy-System einen Vorgang zu einer bereits verwendeten externalid ablehnen. 2. Antworten von ClickandBuy Nach Empfang des Calls RefundRequest reagiert ClickandBuy folgendermaßen: Gibt die TransactionID der ursprünglichen PayTransaction zurück. Gibt den Status zurück. Gibt Ihre optionale externalid (ID Ihres Systems) zurück. 62

63 8.5.2 Stornierung 1. Aufruf des E-Commerce-Systems für die Stornierung Generieren Sie einen Call CancelRequest und senden Sie ihn an ClickandBuy. Verwenden Sie den folgenden Pflichtparameter: Typ Parameter Erläuterung CancelRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) cancelmode cancelidentifier Modus der Stornierung. Wahlweise kann eine Transaktion, eine Zahlungsvereinbarung oder beides storniert werden. ID der Transaktion oder der Zahlungsvereinbarung welche storniert werden soll. Cab:CancelIdentifier ist ein zusammengesetzter Datentyp und beinhaltet entweder eine Transaktions-ID oder eine RecurringPaymentAuthorization-ID. 2. Antworten von ClickandBuy Nach Empfang des Calls CancelRequest reagiert ClickandBuy folgendermaßen: Gibt die TransactionID der ursprünglichen PayTransaction zurück. Gibt den Status zurück Gutschrift 1. Aufruf des E-Commerce-Systems für die Gutschrift Generieren Sie einen Call CreditRequest und senden Sie ihn an ClickandBuy. Verwenden Sie mindestens folgende Pflichtparameter: Typ Parameter Erläuterung CreditRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) amount recipient Betrag und Währung, die gutgeschrieben werden sollen. Cab:Money ist ein Zusammengesetzter Datentyp und beinhaltet sowohl den Betrag als auch die Währung. Identifikation des Kunden. Cab:CreditRecipientIdentifier ist ein Zusammengesetzter Datentyp und beinhaltet entweder eine Kundenreferenznummer oder die -Adresse des Kunden. 63

64 Verwenden Sie optional die zusätzlichen Parameter: Typ Parameter API-Beschreibung CreditRequestDetails (vgl. Seite Fehler! Textmarke nicht definiert.) Consumer Language externalid orderdetails Ausgabesprache der automatisierten , die ClickandBuy an den Kunden versendet. Ist keine Sprache angegeben, wird die Standardsprache Englisch verwendet. ID Ihres Systems. Wir empfehlen, immer eine eigene MerchantID beim CreditRequest mitzugeben, um doppelte Buchungen zu vermeiden. Sollte der Kommunikationsweg für die Rückantwort in irgendeiner Weise gestört sein, kann das ClickandBuy-System einen erneuten Versuch dieser Buchung mit dieser externalid ablehnen. Zusätzlich zur consumerlanguage und zur externalid können für den creditrequest noch die orderdetails (Details zur Bestellung) übergeben werden Beachten Sie, dass bei Versenden des Calls CreditRequest genügend E- Geld auf Ihrem Konto sein muss. Bei Gutschrift auf eine -Adresse reserviert ClickandBuy das Geld für 30 Tage. Löst der Kunde in diesem Zeitraum die Gutschrift nicht ein, wird das E-Geld wieder freigegeben. Bei Gutschriften auf eine Kundenreferenznummer muss diese nicht vom Kunden eingelöst werden und kann in Folge auch nicht verfallen. Sie können eine Gutschrift auf eine -Adresse stornieren, solange sie noch nicht vom Kunden eingelöst wurde. Verwenden Sie hierfür den Call CancelRequest. 2. Antworten von ClickandBuy Nach Empfang des Calls CreditRequest reagiert ClickandBuy folgendermaßen: Gibt den Status zurück. Gibt Ihre optionale externalid (ID Ihres Systems) zurück. 64

65 9 Der Merchant Messaging Service (MMS) Der Merchant Messaging Service (MMS) ist ein Push-Service, der Ihnen in Nahzeit Aktualisierungen der Transaktionsstatus an eine HTTPS-URL übermittelt, unter der Sie das empfangene XML übersetzen und weiterverarbeiten können. Zum Beispiel: Wenn bei einer PayTransaction der Status auf PENDING stand, weil das Geld noch nicht eingegangen ist, wechselt er zum Status SUCCESS, wenn die Zahlung prozessiert wurde. Nähere Informationen zu den verschiedenen Status entnehmen Sie bitte dem Abschnitt Die Status in den Transaktionen, Seite Events individuell einrichten Die Statusänderungen von Bezahlvorgängen heißen in der ClickandBuy-API Events. Sofern nicht anders eingestellt, wird Ihr System von jedem Event informiert. Sie können jedoch in Ihrem Anbieterkonto Abonnements der Events individuell konfigurieren und damit den Erhalt einzelner Event-Typen abbestellen oder auch wieder hinzufügen. Für jede Transaktionsart können Sie festlegen, von welcher Statusänderung Sie informiert werden möchten (z. B. nur vom Status SUCCESS). Damit wird Ihr System nicht mit überflüssigen Nachrichten belastet. Bei Bedarf können Sie Events erneut versenden lassen, jedoch ist deren Vorhaltezeit auf 90 Tage begrenzt. Ältere Events können nicht mehr erneut versendet werden. 9.2 Voraussetzungen für die Event-Übermittlung Die Abonnements von Events verwalten Sie in Ihrem Anbeiterkonto für jedes Projekt einzeln. Events werden per HTTP-Post-Parameter XML als XML an Ihr Push-Skript übermittelt. Ihr Skript muss das XML aufnehmen und auswerten. Hierfür müssen Sie in Ihrem Anbieterkonto für jedes Projekt die Adresse Ihres Skripts als Push-URL hinterlegen. Bei der Konfiguration der Push-URL wird die Erreichbarkeit des Skripts überprüft. Zudem muss es per SSL gesichert sein und ein gültiges SSL-Zertifikat besitzen. Das heißt, es kann durch die standard java6 root certificates validiert werden und ist für die korrekte Domain und Zeit ausgestellt. Beachten Sie bitte, dass jedes Event eine eindeutige ID besitzt und diese IDs inkrementell vergeben werden. So lässt sich jeder Status einer Transaktion sequenziell zurückverfolgen. 65

66 9.2.1 Beispiel eines MMS-Push-Skripts in Pseudocodenotation program MMS PUSH Script ReadPOSTedParameter_xml; CreateAndOpenANewFile; SavePOSTedParameter_xml_in_File; ParseFile; CheckSignatureForAuthentication; if ParsedContentIsOfInterest then ProcessParsedContentInDataBase exit; htmloutput_ok; end MMS PUSH Script Der MMS-Push-Prozess transportiert pro Kommunikation mehrere Events in einer Event-Liste. Dies führt zu einer deutlich schnelleren Informationsweitergabe und spart Ressourcen auf beiden Seiten. Die entsprechenden Schemata entnehmen Sie dem Abschnitt MMS-Typen: mms_1_1_0.xsd, Seite 94. Beispiele für Events finden Sie ab Seite Zur Authentifikation des XML Um sicherzustellen, dass das XML tatsächlich von ClickandBuy stammt und unterwegs nicht manipuliert wurde, ist jeder Push-Nachricht eine Signatur (<signature/>) beigefügt. Diese enthält einen Hashwert, der aus einem nur Ihnen und ClickandBuy bekannten Schlüssel (<MMS sharedkey>) und dem übermittelten XML selbst errechnet wurde. Nachdem Ihr Push-Skript das XML erhalten hat, muss es lediglich den Hashwert errechnen und mit dem mitgesendeten Wert vergleichen. Bei Übereinstimmung können Sie sicher sein, dass der Inhalt des XML von ClickandBuy kommt. Sollte es keine Übereinstimmung geben, liegt entweder Ihrerseits ein Fehler in der Hashwertermittlung vor oder das XML wurde von Dritten manipuliert bzw. stammt nicht von ClickandBuy Den Hashwert berechnen 1. Suchen und speichern Sie den Hashwert im Tag <signature /> im XML-Body. 2. Entfernen Sie den Hashwert aus dem XML-Body (der Tag enthält keinen Wert, ist aber noch im XML vorhanden: <signature />). 3. Erstellen Sie einen SHA-1 Hash wie folgt: SHA1(<MMS sharedkey><xml_body_ohne_signature>) 66

67 Beachten Sie die folgenden Hinweise: Der <MMS sharedkey> wird dem XML-Body ohne Trennzeichen vorangesetzt. Das XML darf ansonsten nicht verändert werden, d. h. es dürfen z. B. keine Leerzeichen entfernt oder eingefügt werden. Newlines müssen im UNIX Format (\n) vorliegen. Der <MMS sharedkey> wird von ClickandBuy für jedes Projekt einzeln generiert. Er kann der Projektkonfiguration Ihres Anbieterkontos entnommen und bei Bedarf geändert werden Den Erhalt der Event-Liste quittieren Den Erhalt der Event-Liste muss das Skript letztlich durch einen HTML-Output OK (print, echo etc.) quittieren (per HTTP 200: OK im Body). Tut es dies nicht, gilt die Event-Liste als nicht übermittelt. Dadurch werden alle neuen Events in eine Queue geschoben und es wird in wachsenden Intervallen versucht, die letzte nicht quittierte Liste zu übermitteln. Als alternative Sicherheitsmaßnahme können Sie überprüfen, ob die Remote Address des Aufrufs im IP Bereich des ClickandBuy Proxies liegt. Die POST Requests vom PROD Proxy kommen aus dem IP Bereich /24. Für die Sandbox (oder Stage/ STAG/ S1) gilt die MMS IP: Diese Variante ist zwar einfacher einzubinden, garantiert jedoch keine Authentizität. 67

68 10 Die XML-Schema-Definitionen (XSDs) Dieses Kapitel enthält die Beschreibungen für die vier Typenarten: pay_1_1_0.xsd: Definition der obersten Typen (Requests und Responses) paytypes_1_1_0.xsd: Typen, Ein- und Ausgabeparameter und Datenfelder der Bezahlarten SOAPTypes_1_1_0.xsd: Typen, Ein- und Ausgabeparameter und Datenfelder, die keiner Bezahlart zugeordnet sind mms_1_1_0.xsd: Typen, Ein- und Ausgabeparameter und Datenfelder des Merchant Messaging Service Definition der obersten Typen: pay_1_1_0.xsd Hier finden Sie die grundlegenden Definitionen der Requests und Responses, also der obersten Typen. Die referenzierte URL lautet: payrequest_request payrequest_request cab:payrequest_request Struktur des PayRequest_Request. payrequest_response payrequest_response cab:payrequest_response Struktur des PayRequest_Response. payrequestrecurring_request payrequestrecurring_ Request cab:payrequestrecurring_ Request Struktur des PayRequestRecurring_Requests. payrequestrecurring_response payrequestrecurring_ Response cab:payrequestrecurring_ Response Struktur des PayRequestRecurring_Response. 68

69 refundrequest_request refundrequest_request cab:refundrequest_ Request Struktur des refundrequest_request. refundrequest_response refundrequest_response cab:refundrequest_ Response Struktur des refundrequest_response. cancelrequest_request cancelrequest_request cab:cancelrequest_ Request Struktur des cancelrequest_request. cancelrequest_response cancelrequest_response creditrequest_request cab:cancelrequest_ Response Struktur des cancelrequest_response. creditrequest_request cab:creditrequest_ Request Struktur des creditrequest_request. creditrequest_response creditrequest_response statusrequest_request cab:creditrequest_ Response Struktur des creditrequest_response. statusrequest_request cab:statusrequest_ Request Struktur des statusrequest_request. 69

70 statusrequest_response statusrequest_response createbatch_request cab:statusrequest_ Response Struktur des statusrequest_response. createbatch_request createbatch_response cab:createbatch_ Request Struktur des createbatch_request. createbatch_response addbatchitem_request cab:createbatch_ Response Struktur des createbatch_response. addbatchitem_request cab:addbatchitem_ Request Struktur des addbatchitem_request. addbatchitem_response addbatchitem_response executebatch_request cab:addbatchitem_ Response Struktur des addbatchitem_response. executebatch_request cab:executebatch_ Request Struktur des executebatch_request. executebatch_response executebatch_response cancelbatch_request cab:executebatch_ Response Struktur des executebatch_response. cancelbatch_request cab:cancelbatch_ Request Struktur des cancelbatch_request. 70

71 cancelbatch_response cancelbatch_response cab:cancelbatch_ Response Struktur des cancelbatch_response. getbatchstatus_request getbatchstatus_request cab:getbatchstatus_ Request Struktur des getbatchstatus_request. getbatchstatus_response getbatchstatus_response cab:getbatchstatus_ Response Struktur des getbatchstatus_response. getaccountingdocuments_request getaccountingdocuments_ Request cab:getaccountingdocum ents_request Struktur des getaccountingdocuments_request. getaccountingdocuments_response getaccountingdocuments_ Response cab:getaccountingdocum ents_response Struktur des getaccountingdocuments_respons e. 71

72 10.2 Typen der Bezahlarten: PayTypes_1_1_0.xsd Hier sind die Typen, Ein- und Ausgabeparameter und Datenfelder der Bezahlarten wie in der WSDL in alphabetischer Reihenfolge aufgeführt. Alle optionalen Parameter sind mit (opt.) bezeichnet. Alle Pflichtparameter sind fett ausgezeichnet. Es handelt sich um einen Auszug. Sie finden die vollständigen SOAP-Typen unter der URL: AccountingDocument settlementaccountid xs:long Eindeutige ID des zugehörigen Settlement Accounts. Date xs:datetime Erstellungsdatum des Dokuments. documenttype cab:accountingdocumentt ype Typ des Dokuments. filetype cab:accountingfiletype File-Typ des Dokuments. filename cab:accountingfilename Dateiname des Dokuments. documentnumber xs:int Sequenzielle Nummer des Dokuments. documentlinks AccountingDocumentLinks cab:accountingdocumentli nks Links auf das Dokument. servicearealink xs:anyuri Merchant Service Area Link auf das Dokument. directlink xs:anyuri Direct-Download Link auf das Dokument (zeitlich begrenzt gültig). AccountingDocumentList (unbound) Name Typ minoccurs maxoccurs Beschreibung document cab:accounting Documents 0 unbounded Struktur mit den Details Dokumente. Paging cab:paginginfo Beschränkung der Ergebnismenge. 72

73 AccountingDocumentType (simple type, enum) Enum values Invoice Settlement Revenue ManualCreditNote manualdebitnote Beschreibung Invoice-Dokument Settlement-Dokument Revenue-Dokument Dokument zur manuellen Kreditierung Dokument zur manuellen Debitierung AccountingFileName AccountingFileName xs:string Dateiname des Dokuments. AccountingFileType (simple type, enum) Enum values PDF CSV Beschreibung Beschränkung des Dateityps auf PDFs. Beschränkung des Dateityps auf CSVs. AddBatchItemDetails batchid xs:long Batch-ID. batchitemdetailslist cab:batchitemdetailslist Struktur mit bis zu 128 einzelnen Items. AddBatchItemProcessingDetails payrequestdetails cab:payrequestdetails Struktur mit allen PayRequest Details. payrequestrecurring Details cab:payrequestrecurring Details Struktur mit allen PayRequestRecurring Details. refundrequestdetails cab:refundrequestdetails Struktur mit allen refundrequest Details. creditrequestdetails cab:creditrequestdetails Struktur mit allen creditrequest Details. cancelrequestdetails cab:cancelrequestdetails Struktur mit allen cancelrequest Details. AddBatchItem_Request 73

74 authentication cab:authentication Struktur mit den API Authentifizierungsparametern. details cab:addbatchitemdetails Struktur für AddBatchItem Details (bis max. 128 Items). AddBatchItem_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. batch cab:batchidstatus Struktur mit Batchstatus. batchitemlist cab:batchitemidstatuslist (opt.) Struktur mit bis zu 128 Batchitemstatus (vgl. Abschnitt 11.5 für einzelne Statuswerte). Authentication merchantid xs:long Eindeutige Anbieter ReferenzID. projectid xs:long Eindeutige ProjektID innerhalb eines Anbieterkontos. token cab:token Eindeutiger Token zur Authentifizierung des Calls. BatchIDStatus batchid xs:long Batch-ID. externalbatchid cab:externalid (opt.) Externe Batch-ID. batchstatus cab:batchstatus (opt.) Der Status der entsprechenden Batch-ID bzw. externen ID (vgl. Abschnitt 11.4). BatchItemDetails externalid cab:externalid (opt.) Eindeutige ID aus dem Anbietersystem. details cab:addbatchitem ProcessingDetails Details des einzufügenden Batchitems. BatchItemDetailsList (unbound) Name Typ minoccurs maxoccurs Beschreibung batchitem Details cab:batch ItemDetails 0 unbounded Struktur mit den Details eines batch item requests. 74

75 BatchItemIDList (unbound) Name Typ minoccurs maxoccurs Beschreibung batchitemid xs:long unbounded 0 Batch Item IDs. Struktur welche bis zu 128 Einträge enthält. BatchItemIDStatus batchitemid xs:long BatchItem ID. externalid cab:externalid (opt.) Eindeutige ID aus dem Anbietersystem. batchitemstatus cab:batchitemstatus (opt.) Status des einzelnen Batchitems (vgl. Kapitel 6.5). resulttransactionid xs:long (opt.) Transaction ID, die für dieses Item angelegt wurde. errordetails cab:errordetails (opt.) Struktur mit Fehlermeldung. BatchItemIDStatusList (unbound) Name Typ minoccurs maxoccurs Beschreibung batchitem cab:batch ItemIDStatus 0 unbounded Struktur mit dem Status oder Fehlerinformationen zu einer entsprechenden ItemID. BatchItemStatus (simple type, enum) Enum values CREATED CANCELLED SUCCESS PENDING_EXECUTION EXECUTING ERROR Beschreibung Ein BatchItem wurde erstellt und dem Batch übergeben: Ein BatchItem wurde durch den Anbieter storniert. Das BatchItem wurde mit einem erfolgreichen Resultat bearbeitet. SUCCESS ist ein finaler Status. Der Batch wurde zur weiteren Bearbeitung geschlossen bzw. gestartet. Als Konsequenz werden alle enthaltenen Items in der Folge prozessiert. Das BatchItem wird gerade bearbeitet. Dies ist ein interner Status und wird nicht an den Anbieter kommuniziert. Das BatchItem wurde mit einem fehlerhaften Resultat bearbeitet. ERROR ist ein finaler Status. BatchStatus (simple type, enum) Enum values CREATED Beschreibung Ein Batch wurde erstellt. BatchItems können nun für eine spätere 75

76 Verarbeitung eingereicht werden. CANCELLED PENDING_EXECUTION EXECUTING EXECUTED Der Batch inklusive aller enthaltenen Items wurde vom Anbieter storniert. CANCELLED ist ein finaler Status. Der Batch wurde zur weiteren Bearbeitung geschlossen bzw. gestartet. Neue Items können nun nicht mehr eingereicht werden: Der Batch wird seitens ClickandBuy ausgeführt: Batch wurde ausgeführt. Erfolg/Misserfolg eines jeden Items erfahren Sie in den einzelnen ItemStatus. EXECUTED ist ein finaler Status. CancelBatchDetails batchid xs:long batchid. CancelBatch_Request authentication cab:authentication Struktur mit Details zur API Authentifizierung. details cab:cancelbatchdetails Struktur für CancelBatchRequest Details. CancelBatch_Response Request TrackingID cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. batch cab:batchidstatus Struktur mit Status des Batchs. CancelIdentifier (choice) transactionid xs:long Eindeutige TransaktionsID. oder recurringpaymentauthorizationid xs:long Eindeutige RPA-ID. CancelMode (simple type, enum) Enum values TX RPA BOTH Beschreibung Stornierung der Transaktion. Stornierung der Zahlungsvereinbarung. Stornierung von Transaktion und verknüpfter Zahlungsvereinbarung. 76

77 CancelRequestDetails cancelmode cab:cancelmode Modus in welchem die Stornierung durchgeführt wird (TX, RPA, BOTH). cancelidentifier cab:cancelidentifier Eindeutige Transaktions- oder RPA-ID. CancelRequest_Request authentication cab:authentication Struktur mit Details zur API Authentifizierung. details cab:cancelrequestdetails Struktur für CancelRequest Details. CancelRequest_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. transaction cab:transactionidstatus Status der Transaktion. CreateBatchDetails externalbatchid cab:externalid (opt.) Externe ID des Batchs aus dem Anbietersystem. CreateBatch_Request authentication cab:authentication Struktur mit Details zur API- Authentifizierung. details cab:createbatchdetails Struktur für CreateBatchRequest Details. CreateBatch_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. batch cab:batchidstatus Struktur mit Status des Batchs. CreditRecipientIdentifier (choice) cab: -Adresse des Gutschriftempfängers. oder 77

78 crn xs:long Kundenreferenznummer des Gutschriftempfängers. CreditRequestDetails amount cab:money Betrag und Währung der Gutschrift. recipient cab:creditrecipientidenti fier Empfänger der Gutschrift. consumerlanguage cab:language (opt.) ISO Sprachcode des Kunden (für Sprache in s). orderdetails cab:orderdetails (opt.) Zahlungsdetails. externalid cab:externalid (opt.) Eindeutige ID aus dem Anbietersystem. CreditRequest_Request authentication cab:authentication Struktur mit Details zur API-Authentifizierung. details cab:creditrequestdetails Struktur für CreditRequest Details. CreditRequest_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. transaction cab:transactionidstatus Status der Transaktion. DateRange after cab:datetime (opt.) Datum nach welchem das Dokument generiert wurde. before cab:datetime (opt.) Datum vor welchem das Dokument generiert wurde. ErrorCode (simple type, enum) Enum values Beschreibung 1 MalformedRequest (siehe Abschnitt 7). 2 AuthentificationFailed (siehe Abschnitt 7). 3 InvalidRequest (siehe Abschnitt 7). 4 TechnicalError (siehe Abschnitt 7). 78

79 ErrorDetailCode (simple type) ErrorDetailCode xs:unsignedint Error-Code-ID ErrorDetails requesttrackingid cab:requesttrackingid (opt.) Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. Code cab:errorcode Fehlercode (siehe Abschnitt 12). detailcode cab:errordetailcode Fehlerdetailcode. description cab:text Fehlerbeschreibung. retry cab:flag Erneuter Versuch sinnvoll? ExecuteBatchDetails batchid xs:long Batch ID. ExecuteBatch_Request authentication cab:authentication Struktur mit Details zur API-Authentifizierung. details cab:executebatchdetails Struktur für ExecuteBatchDetails Details. ExecuteBatch_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. batch cab:batchidstatus Struktur mit Status des Batchs. ExternalIDList (unbound) Name Typ maxoccurs Beschreibung ExternalID cab:externalid unbounded Eindeutige ID aus dem Anbietersystem. GetAccountingDocumentDetails Date cab:daterange (opt.) Struktur mit Datumsspanne. documenttype cab:accountingdocumentt ype (opt.) Beschränkung des Dokumententypen. 79

80 filetype filename cab:accountingfiletype (opt.) cab:accountingfilename (opt.) Beschränkung des Dateitypen. Dateiname des Dokuments. documentnumber cab:intrange (opt.) Sequenzielle Dokumentennummer. paging cab:pagingsetting (opt.) Beschränkung der Ergebnissmenge. GetAccountingDocuments_Request authentication cab:authentication Struktur mit Details zur API- Authentifizierung. details cab:getaccountingdocume ntdetails Struktur für GetAccountingDocument Details. GetAccountingDocuments_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. documentlist cab:accountingdocumentli st Struktur mit Dokumenten. GetBatchStatusDetails batchid xs:long (opt.) Batch ID. externalbatchid cab:externalid (opt.) Eindeutige ID aus dem Anbietersystem. batchitemidlist cab:batchitemidlist (opt.) Struktur mit Batch IDs. GetBatchStatus_Request authentication cab:authentication Struktur mit Details zur API- Authentifizierung. details cab:getbatchstatusdetails Struktur für GetBatchStatus Details. GetBatchStatus_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. batch cab:batchidstatus Struktur mit Status des Batchs. 80

81 batchitemlist cab:batchitemidstatuslist (opt.) Struktur mit bis zu 128 Batchitemstatus. IntRange from xs:int (opt.) Minimale Dokumentennummer (Inklusive). until xs:int (opt.) Maximale Dokumentennummer (Inklusive). NumberLimit (simple type) Typ mininclusive maxinclusive Beschreibung xs:int Die maximale Anzahl von Zahlungen, die durch eine RPA durchgeführt werden können. OrderDetailItem itemtype cab: OrderDetailItemType Definiert den Typ eines order detail items (= einer Einheit), was die Darstellung auf der ClickandBuy- Checkout-Seite beeinflusst. TEXT: Eine einfache Textzeile wird angezeigt. ITEM: Tabelle mit Beschreibung, Quantität, Stückpreis und Gesamtpreis wird angezeigt. SUBTOTAL: Tabelle mit Beschreibung und Gesamtpreis wird im Zwischensummen-Format angezeigt. VAT: Tabelle mit Beschreibung und Gesamtpreis wird in MWSt-Format angezeigt. TOTAL: Tabelle mit Beschreibung und Gesamtpreis wird in Gesamtpreis-Format angezeigt. description cab:orderdetailtext Text als Bestellbeschreibung. quantity cab:quantity (opt.) Anzahl von Einheiten. unitprice cab:money (opt.) Preis einer Einheit, zusammengesetzt aus Betrag und Währung totalprice cab:money (opt.) Gesamtpreis, zusammengesetzt aus Betrag und Währung. OrderDetailItemList (unbound) Name Typ minoccurs maxoccurs Beschreibung Item cab:orderdetailitem 0 unbounded Detail eines einzigen Bestellitems. 81

82 OrderDetailItem Type (simple type, enum) Enum values TEXT ITEM SUBTOTAL VAT TOTAL Beschreibung Eine einfache Textzeile wird angezeigt. Tabelle mit Beschreibung, Quantität, Stückpreis und Gesamtpreis wird angezeigt. Tabelle mit Beschreibung und Gesamtpreis wird im Zwischensummen- Format angezeigt. Tabelle mit Beschreibung und Gesamtpreis wird in MWSt-Format angezeigt. Tabelle mit Beschreibung und Gesamtpreis wird in Gesamtpreis-Format angezeigt: OrderDetailText Typ minlength maxlength Beschreibung xs:string Text zur Bestellbeschreibung. OrderDetails text cab:orderdetailtext (opt.) Text zur Bestellbeschreibung. itemlist PagingInfo cab:orderdetailitemlist (opt.) Liste der Bestell-Items (maximal 128). Name Typ mininclusive Beschreibung skip xs:int 0 Zu überspringende Resultate maxresults xs:int 1 Gesamtanzahl der angefragten Resultate. resultcount xs:int 0 Gesamtanzahl der Resultate im Response. totalresultcount xs:int 0 Gesamtanzahl der Resultate entsprechend der Filterkriterien. pagingsetting Name Typ mininclusive Beschreibung skip maxresults xs:int (opt.) xs:int (opt.) 0 Zu überspringende Resultate 1 Max. Anzahl an zu liefernden Resultaten. 82

83 PayRequestDetails amount cab:money Betrag und Währung des PayRequests. orderdetails cab:orderdetails (opt.) Details zur Bestellung (Warenkorb). billing cab:legalentity (opt.) Rechnungsempfänger. shipping cab:legalentity (opt.) Lieferungsempfänger. basketrisk cab:riskscore (opt.) Risikoscoring des Warenkorbs. clientrisk cab:riskscore (opt.) Risikoscoring des Kunden authexpiration cab:expirationtime (opt.) Haltbarkeit einer nicht autorisierten Zahlung. confirmexpiration cab:expirationtime (opt.) Haltbarkeit einer nicht bestätigten Zahlung. successexpiration cab:expirationtime (opt.) Haltbarkeit einer nicht erfolgreichen Zahlung. successurl cab:url (opt.) URL, auf die der Kunde im Erfolgsfall geleitet wird. failureurl cab:url (opt.) URL, auf die der Kunde im Nichterfolgsfall geleitet wird. createrecurring cab:recurringpayment Authorization (opt.) Struktur für das Anlegen einer RPA. externalid cab:externalid (opt.) Eindeutige ID aus dem Anbietersystem. consumeripaddress cab:ipaddress (opt.) IP-Adresse des Kunden. consumerlanguage cab:language (opt.) ISO Sprachcode. consumercountry cab:country (opt.) ISO alpha-2 Ländercode. PayRequestRecurringDetails amount cab:money Betrag und Währung des PayRequestRecurring. recurringpayment AuthorizationID xs:long ID der RPA. orderdetails cab:orderdetails (opt.) Details zur Bestellung (Warenkorb). billing cab:legalentity (opt.) Rechnungsempfänger. shipping cab:legalentity (opt.) Lieferungsempfänger. basketrisk cab:riskscore (opt.) Risikoscoring des Warenkorbs. clientrisk cab:riskscore (opt.) Risikoscoring des Kunden. successexpiration cab:expirationtime (opt.) Haltbarkeit einer nicht erfolgreichen Zahlung. 83

84 externalid cab:externalid (opt.) Eindeutige ID aus dem Anbietersystem. PayRequestRecurring_Request authentication cab:authentication Struktur mit Details zur API- Authentifizierung. details cab:payrequestrecurring Details Struktur für PayRequestRecurring Details. PayRequestRecurring_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. transaction cab:transactionidstatus Status der Transaktion. PayRequest_Request authentication cab:authentication Struktur mit Details zur API-Authentifizierung. details cab:payrequestdetails Struktur für PayRequestDetails. PayRequest_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. transaction cab:transactionidstatus Status der Transaktion. RecurringPaymentAuthorization description cab:text Beschreibungstext der RPA. numberlimit cab:numberlimit (opt.) Die maximale Anzahl von Zahlungen, die über diese RPA angestoßen werden können. amountlimit cab:money (opt.) Der maximale Betrag und Währung, die über diese RPA abgerechnet werden können. expiredate xs:date (opt.) Ablaufdatum der RPA. revokableby Consumer cab:flag (opt.) Gibt an, ob eine RPA vom Kunden widerrufen werden kann. 84

85 RecurringPaymentAuthorizationIDStatus recurringpayment AuthorizationID recurringpayment AuthorizationStatus xs:long cab:recurringpayment AuthorizationStatus Eindeutige Referenz der RPA. Status der RPA. RefundRequestDetails amount cab:money Betrag und Währung der Anfrage. transactionid xs:long Eindeutige TransaktionsID von CaB. orderdetails cab:orderdetails (opt.) Details zur Zahlung. externalid cab:externalid (opt.) Eindeutige TransaktionsID aus dem Anbietersystem. RefundRequest_Request authentication cab:authentication Struktur mit Details zur API-Authentifizierung. details cab:refundrequestdetails Struktur für RefundRequestDetails. RefundRequest_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. transaction cab:transactionidstatus Status der Transaktion RequestTrackingID (simple type) Name Typ minlength maxlength Beschreibung Request TrackingID xs:string Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. StatusRequestDetails (choice) transactionidlist cab:transactionidlist (opt.) oder Liste von TransactionIDs (bis zu 128 Elemente). externalidlist cab:externalidlist (opt.) Liste von eindeutigen TransaktionsIDs aus dem Anbietersystem (bis zu 128 Elemente). 85

86 StatusRequest_Request authentication cab:authentication Struktur mit Details zur API-Authentifizierung. details cab:statusrequestdetails Struktur für StatusRequestDetails. StatusRequest_Response requesttrackingid cab:requesttrackingid Eindeutige Referenz der Anfrage, von ClickandBuy erstellt. transactionlist cab:transactionstatus List Liste mit dem jeweiligen Transaktionsstatus. TransactionIDList (unbound sequence) transactionid xs:long Eindeutige TransaktionsID, von ClickandBuy erstellt. TransactionIDStatus transactionid xs:long (opt.) Eindeutige TransaktionsID, von ClickandBuy erstellt. externalid cab:externalid (opt.) Eindeutige TransaktionsID aus dem Anbietersystem. crn xs:long (opt.) Eindeutige Kundenreferenznummer. transactionstatus transactiontype cab:transactionstatus (opt.) cab:transactiontype (opt.) Statusbeschreibung einer Transaktion. Transaktionstyp: PAY: Zahlung CREDIT: Gutschrift REFUND: Teilgutschrift einer Transaktion errordetails cab:errordetails (opt.) Struktur mit Fehlermeldung redirecturl cab:url (opt.) Redirect URL, auf die der Kunde geleitet werden muss. createdrecurring PaymentAuthorization TransactionStatus (simple type, enum) cab:recurringpaymentauthorizationidstatus (opt.) Enum values Verwendet bei Beschreibung CREATED PayTransaction, Die Transaktion wurde angenommen und 86

87 Enum values Verwendet bei Beschreibung CreditTransaction, RefundTransaction PENDING_VERIFICATION PayTransaction EXPIRED ABORTED DECLINED CANCELLED IN_PROGRESS SUCCESS PayTransaction, CreditTransaction, RefundTransaction PayTransaction, CreditTransaction. PayTransaction, CreditTransaction, RefundTransaction PayTransaction, CreditTransaction, RefundTransaction PayTransaction, CreditTransaction, RefundTransaction PayTransaction, CreditTransaction, RefundTransaction angelegt und wartet auf weitere Aktionen, z. B. Kundenbestätigung bzw. - verifizierung, Ablaufen oder Stornierung. Die PayTransaction wurde zumindest einmalig angesehen (d. h. die RedirectURL wurde aufgerufen). Der Kunde hat jedoch noch keine Registrierung bzw. kein Login durchgeführt, was für eine Bestätigung erforderlich ist. Der Kunde wurde nicht auf die ClickandBuy-Checkout-Seite weitergeleitet oder hat sich dort nicht rechtzeitig eingeloggt bzw. registriert. Oder er hatte für eine zu lange Zeit zu wenig Guthaben auf dem Konto, ohne dieses aufzufüllen. Der Kunde hat die Transaktion abgebrochen. ClickandBuy hat die Transaktion abgewiesen. Die Transaktion wurde vom Anbieter storniert. Die Transaktion ist in Bearbeitung, d. h. es wird z. B. auf den Geldeingang des Kunden gewartet. Die Transaktion wurde erfolgreich bearbeitet (der Anbieter kann liefern, gutschreiben, Zugriff gewähren etc.). Der Anbieter trägt das Risiko. PAYMENT_PENDING PayTransaction Die PayTransaction wurde zurück gebucht. Das Mahnwesen beginnt, es folgt entweder der Geldeingang oder der Inkassoprozess. BOOKED_OUT PayTransaction Der entsprechende Betrag wurde aus dem System ausgebucht. BOOKED_IN PayTransaction Der entsprechende Betrag wurde wieder in das System eingebucht. PAYMENT_GUARANTEE PayTransaction ClickandBuy garantiert die PayTransaction. Das bedeutet, dass ab 87

88 Enum values Verwendet bei Beschreibung TransactionStatusList (unbound) diesem Zeitpunkt keine Rück- oder Ausbuchung stattfinden wird. Das Clickandbuy-System meldet jede Änderung eines Status. Sollte eine PAYMENT_GUARANTEE nicht erfolgen, erfolgt auch keine Änderungsmeldung und die Transaktion bleibt im Status SUCCESS. Name Typ min Occ urs maxoccu rs Beschreibung transaction cab:transactionidstatus 0 unbounded Struktur mit dem Status einer TransaktionsID bzw. ExternalID oder eine Struktur mit Fehlermeldungen zur jeweiligen TransactionID. TransactionType (simple type, enum) Enum values PAY CREDIT REFUND Beschreibung Zahlung. Gutschrift. Teilgutschrift auf eine bestehende Transaktion. 88

89 10.3 SOAP-Typen: SOAPTypes_1_1_0.xsd Hier sind allgemeine SOAP-Typen, Parameter und Datenfelder wie in der WSDL in alphabetischer Reihenfolge aufgeführt. Diese Typen sind allgemeiner Art und keiner bestimmten Bezahlart zugeordnet. Es handelt sich um einen Auszug. Sie finden die vollständigen SOAP-Typen unter der URL: Amount (simple type) Name Typ maxinclusive fractiondigits Beschreibung Amount xs:decimal Betrag. Currency (simple type) Name Typ minlength maxlength Beschreibung Currency xs:string 3 3 ISO 4217 alpha-3 Währungscode. Date (simple type) Date xs:date Datum. DateTime (simple type) DateTime xs:datetime Datum und Zeit. (simple type) Name Typ min Length max Length Pattern Beschreibung xs:string 0 50 ([-_.A-Za-z0-9]+)@ ([-_.A-Za-z0-9]+)\. [A-Za-z]{2,} -Adresse. ErrorMessage (simple type) Name Typ minlength maxlength Beschreibung ErrorMessage xs:string Fehlermeldung. ExpirationTime (simple type) Name Typ minlength maxlength Beschreibung ExpirationTime xs:int Ablaufzeit in Minuten. 89

90 Expiry month cab:month Ablaufdatum: Monat (1 Januar; 2 Februar; etc.). Year cab:year Ablaufdatum: Jahr. ExpiryDate ExpiryDate xs:date Ablaufdatum. ExternalID (simple type) Name Typ minlength maxlength Beschreibung ExternalID xs:string Eindeutige TransaktionsID aus dem Anbietersystem. Flag (simple type) Flag xs:boolean Bool scher Wert. Language (simple type) Name Typ minlength maxlength Beschreibung Language xs:string 2 2 ISO Sprachcode. MerchantID (simple type) Name Typ min Length max Length whitespace Beschreibung MerchantID xs:string 3 50 collapse Eindeutige Anbieter- Referenz. Money amount cab:amount Betrag der Transaktion. currency cab:currency Währung der Transaktion. 90

91 Month (simple type, enum) Typ Enum values Beschreibung xs:unsignedbyte 1 Januar 2 Februar 3 März 4 April 5 Mai 6 Juni 7 Juli 8 August 9 September 10 Oktober 11 November 12 Dezember OrderDescription (simple type) OrderDescription xs:string Beschreibung der Bestellung (steht auf Kundenabrechnungsdokumenten). OrderID (simple type) Name Typ minlength maxlength Beschreibung OrderID xs:string Referenz der Bestellung aus dem Anbietersystem (sollte eindeutig sein, obgleich dies seitens ClickandBuy nicht überprüft wird). Quantity (simple type) Name Typ mininclusive maxinclusive Beschreibung Quantity xs:int Anzahl der Items. 91

92 RecurringPaymentAuthorizationStatus (simple type, enum) Typ xs:string Enum values CREATED PENDING_VERIFICATION EXPIRED ABORTED DECLINED CANCELLED AUTHORIZED EXHAUSTED SessionID (simple type) Name Typ min Length max Length whitespace Beschreibung SessionID xs:string 3 50 collapse SessionID im Anbieterwebshop StartDate month cab:month Startdatum: Monat (1 Januar; 2 Februar usw.). year cab:year Startdatum: Jahr. Time (simple type) Time xs:time Zeit. Timestamp (simple type) Timestamp xs:datetime Zeitstempel (vgl. Abschnitt 5.3). Token (simple type) Name Typ min Length max Length whitespace Beschreibung token xs:string collapse Sicherheitstoken zur Authentifizierung. 92

93 TransactionRefNo (simple type) Name Typ minlength maxlength Beschreibung TransactionRefNo xs:string Referenz zur Transaktion. URL (simple type) URL xs:anyurl URL:Internetadresse (Homepage). Year (simple type) Name Typ minlength maxlength Pattern Beschreibung Year xs:string 0 4 [1-2]\d{3} Jahr. 93

94 10.4 MMS-Typen: mms_1_1_0.xsd Hier sind Typen, Ein- und Ausgabeparameter und Datenfelder für den Merchant Messaging Service aufgeführt. Es handelt sich um einen Auszug. Die kompletten MMS-Typen finden Sie unter der URL: Alle optionalen Parameter sind mit (opt.) bezeichnet. Alle Pflichtparameter sind fett ausgezeichnet. Eventlist eventlist cab:eventlist Eventliste:Rootelement. EventList (unbounded sequence) Name Typ Min Occurs Max Occurs Beschreibung payevent refundevent creditevent batchevent recurringpayment AuthorizationEvent cab:payevent Details cab:refund EventDetails cab:creditevent Details cab:batchevent Details cab:rpaevent Details 0 unbounded PayTransaction-Event: Rootelement. 0 unbounded RefundTransaction- Event: Rootelement. 0 unbounded CreditTransaction-Event: Rootelement. 0 unbounded Batch-Event: Rootelement. 0 unbounded RecurringPayment Authorization-Event: Rootelement. PayEventDetails merchantid xs:long Eindeutige AnbieterID. projectid xs:long Eindeutige ProjektID. eventid xs:long Eindeutige EventID (innerhalb eines Projekts). creationdatetime cab:datetime (opt.) Erstellungsdatum des Events. transactionid xs:long Eindeutige TransaktionsID von ClickandBuy: externalid cab:externalid (opt.) Eindeutige TransaktionsID aus dem Anbietersystem. 94

95 crn xs:long (opt.) Eindeutige ClickandBuy- Kundenreferenznummer. transactionamount cab:money Betrag und Währung der Transaktion. merchantamount cab:money (opt.) Betrag und Währung für den Anbieter (bei Währungsumrechnungen). oldstate cab:transactionstatus (opt.) Alter Status einer Transaktion. newstate cab:transactionstatus Neuer Status einer Transaktion. RefundEventDetails merchantid xs:long Eindeutige AnbieterID. projectid xs:long Eindeutige ProjektID. eventid xs:long Eindeutige EventID (innerhalb eines Projekts). creationdatetime cab:datetime Erstellungsdatum des Events. refundtransactionid xs:long Eindeutige RefundTransactionID von ClickandBuy. externalid cab:externalid (opt.) Eindeutige TransaktionsID aus dem Anbietersystem. Associated TransactionID xs:long Eindeutige ID der assoziiertentransaktion. crn xs:long (opt.) Eindeutige ClickandBuy Kundenreferenznummer. transactionamount cab:money Betrag und Währung der Transaktion. merchantamount cab:money (opt.) Betrag und Währung für den Anbieter (bei Währungsumrechnungen). oldstate cab:transactionstatus (opt.) Alter Status einer Transaktion. newstate cab:transactionstatus Neuer Status einer Transaktion: CreditEventDetails merchantid xs:long Eindeutige AnbieterID. projectid xs:long Eindeutige ProjektID. eventid xs:long Eindeutige EventID (innerhalb eines Projekts). creationdatetime cab:datetime Erstellungsdatum des Events. 95

96 transactionid xs:long Eindeutige TransaktionsID von ClickandBuy. externalid cab:externalid (opt.) Eindeutige TransaktionsID aus dem Anbietersystem. recipient cab:creditrecipientidentifier Gutschriftsempfänger. crn xs:long (opt.) Eindeutige ClickandBuy Kundenreferenznummer. transactionamount cab:money Betrag und Währung der Transaktion. merchantamount cab:money (opt.) Betrag und Währung für den Anbieter (bei Währungsumrechnungen). oldstate cab:transactionstatus (opt.) Alter Status einer Transaktion. newstate cab:transactionstatus Neuer Status einer Transaktion. BatchEventDetails merchantid xs:long Eindeutige AnbieterID. projectid xs:long Eindeutige ProjektID. eventid xs:long Eindeutige EventID (innerhalb eines Projekts). creationdatetime cab:datetime Erstellungsdatum des Events. batchid xs:long Eindeutige Referenz des Batchjobs. externalbatchid cab:externalid Eindeutige externe Referenz des Batchjobs. itemcount xs:long Anzahl der Items im Batch. oldstate cab:batchstatus Alter Status des Batches. newstate cab:batchstatus Neuer Status des Batches. batchitemlist cab:batchitemeventlist Liste der einzelnen Batchitems. BatchItemEventDetails batchitemid xs:long Eindeutige Referenz des Batchitems. externalid cab:externalid (opt.) Eindeutige externe Referenz des Batchitems. batchitemstatus cab:batchitemstatus Status des Batchitems. resulttransactionid xs:long (opt.) Eindeutige Result TransactionID. errordetails cab:errordetails (opt.) Fehlermeldung. 96

97 BatchItemEventList Name Typ MinOccurs MaxOccurs Beschreibung batchitem cab:batchitem EventDetails 0 unbound Struktur mit einer Liste von Batchitems. RPAEventDetails recurringpaymen tauthorizationid xs:long Eindeutige RPA-ID. merchantid xs:long Eindeutige AnbieterID. projectid xs:long Eindeutige ProjektID. eventid xs:long Eindeutige EventID (innerhalb eines Projekts). creationdatetime cab:datetime Erstellungsdatum des Events. transactionid xs:long Eindeutige TransaktionsID von ClickandBuy. externalid cab:externalid (opt) Eindeutige TransaktionsID aus dem Anbietersystem. crn xs:long (opt.) Eindeutige Kundenreferenznummer bei ClickandBuy. amount cab:money (opt.) Definiert den maximal möglichen Betrag und Währung für erfolgreiche PayTransaction, die über eine RPA eingezogen werden können. Fehlt der Wert, existiert kein Limit. oldstate newstate cab:recurringpayment AuthorizationStatus (opt) cab:recurringpayment AuthorizationStatus Alter Status der RPA. Neuer Status der RPA. remainingamount cab:money (opt.) Noch übriggebliebener/offener Betrag und Währung. remainingretries xs:long (opt.) Definiert die maximal mögliche Anzahl für erfolgreiche PayTransactions, die noch über eine RPA eingezogen werden können. Fehlt der Wert, existiert kein Limit. validuntil cab:date (opt.) Definiert das Ablaufdatum, bis zu dem die RPA Gültigkeit behält. (23:59:59 UTC des aktuellen Tags). Fehlt der Wert, existiert kein Limit. 97

98 11 Die Status in den Transaktionen Wie beschrieben, unterlaufen die Transaktionen während des Bezahlprozesses verschiedene Status. Die Statusänderungen unterscheiden sich je nach der Art der Transaktion. Nachfolgend finden Sie Diagramme der möglichen Statusabläufe für die verschiedenen Transaktionstypen. Die Status werden für jeden Transaktionstyp erläutert PayTransaction und PayTransactionRecurring Statusablaufdiagramm für die Transaktion PayTransaction: 98

99 Statusablaufdiagramm für die Transaktion PayTransactionRecurring: 99

100 Definition der Status für die Transaktionen PayTransaction und PayTransactionRecurring: Status Final Definition CREATED PENDING_VERIFICATION Eine PayTransaction wurde erstellt. Die Transaktion bleibt im Status CREATED, bis der Kunde auf die RedirectURL geleitet wurde und die erste ClickandBuy-Checkout-Seite gesehen hat. Nachdem der Kunde die auf die RedirectURL geleitet wurde und die erste ClickandBuy-Checkout-Seite gesehen hat. EXPIRED X 'Der Kunde wurde nicht auf die ClickandBuy- Checkout-Seite weitergeleitet, oder hat sich dort nicht rechtzeitig eingeloggt bzw. registriert. Oder er hatte für eine zu lange Zeit zu wenig Guthaben auf dem Konto, ohne dieses aufzufüllen. IN_PROGRESS Der Kunde hat die Transaktion bestätigt, das Clearing wurde gestartet. DECLINED X ClickandBuy hat die Transaktion für diesen Kunden zurückgewiesen. ABORTED X Der Kunde hat die Transaktion aktiv abgebrochen. SUCCESS Das Clearing war erfolgreich, was bedeutet, dass der Anbieter höchstwahrscheinlich das Geld der Transaktion erhalten wird. Ggf. hat ClickandBuy diese Zahlung manuell verifiziert. CANCELLED X Entweder ClickandBuy oder der Anbieter haben die Transaktion storniert. PAYMENT_PENDING BOOKED_OUT % des eingezogenen Betrags wurden zurückgebucht (Rücklastschrift, Rückbelastung etc.). Der Kunde bzw. die Transaktion befindet sich im Inkassoprozess. BOOKED_IN X Der Kunde hat während des Inkassoprozesses bezahlt, der Betrag wurde wieder ins System eingebucht. PAYMENT_GUARANTEE X ClickandBuy garantiert, dass der Anbieter das Geld der Transaktion erhält. Der Status PAYMENT_GUARANTEE ist optional (abhängig von vertraglichen Regelungen). Das Clickandbuy-System meldet jede Änderung eines Status. Sollte eine PAYMENT_GUARANTEE nicht erfolgen, erfolgt auch keine Änderungsmeldung und die Transaktion bleibt im Status SUCCESS. 100

101 11.2 RefundTransaction Statusablaufdiagramm für die Transaktion RefundTransaction: Definition der Status für die Transaktion RefundTransaction: Status Final Definition SUCCESS X Die Transaktion wurde erfolgreich ausgeführt. DECLINED X ClickandBuy hat die Transaktion für diesen Kunden abgelehnt. 101

102 11.3 CreditTransaction Statusablaufdiagramm für die Transaktion CreditTransaction: Definition der Status für die Transaktion CreditTransaction: Status Final Definition CREATED IN_PROGRESS Eine CreditTransaction wurde erstellt. Sie kann vom Besitzer der -Adresse eingelöst werden. Der Kunde hat die Transaktion bestätigt oder eingelöst und wird von ClickandBuy bearbeitet. CANCELLED X Der Anbieter hat die Transaktion widerrufen. ABORTED X Der Kunde hat die Transaktion abgebrochen und das Geld nicht eingelöst. EXPIRED X Die Transaktion wurde nicht eingelöst und ist abgelaufen. SUCCESS X Die Transaktion wurde erfolgreich ausgeführt. DECLINED X ClickandBuy hat die Transaktion für diesen Kunden abgelehnt. 102

103 11.4 Batch Statusablaufdiagramm für die Transaktion Batch: Definition der Status für die Transaktion Batch: Status Final Definition CREATED Ein Batch wurde erstellt. BatchItems können nun für eine spätere Verarbeitung eingereicht werden. CANCELLED X Der Batch inklusive aller enthaltenen Items wurde vom Anbieter storniert. PENDING_EXECUTION EXECUTING Der Batch wurde zur weiteren Bearbeitung geschlossen bzw. gestartet. Neue Items können nun nicht mehr eingereicht werden. Der Batch wird seitens ClickandBuy ausgeführt. EXECUTED X Der Batch wurde ausgeführt. Erfolg/Misserfolg eines jeden Items erfahren Sie durch den API-Call getbatchstatus in den einzelnen Itemstatus. 103

104 11.5 BatchItem Statusablaufdiagramm für die Transaktion BatchItem: Definition der Status für die Transaktion BatchItem: Status Final Definition CREATED Ein Batch wurde erstellt und dem Batch übergeben. CANCELLED X Der Batch inklusive aller enthaltenen Items wurde vom Anbieter storniert. PENDING_EXECUTION Der Batch wurde zur weiteren Bearbeitung geschlossen bzw. gestartet. Als Konsequenz werden alle enthaltenen Items in der Folge prozessiert. SUCCESS X Das BatchItem wurde mit einem erfolgreichen Resultat bearbeitet. ERROR X Das BatchItem wurde mit einem fehlerhaften Resultat bearbeitet. 104

105 11.6 RecurringPaymentAuthorization Statusablaufdiagramm für die Transaktion RecurringPaymentAuthorization: Definition der Status für die Transaktion RecurringPaymentAuthorization: Status Final Definition CREATED AUTHORIZED Eine RPA wurde erstellt. Der Kunde hat die RPA autorisiert, indem er den dazugehörigen PayRequest bestätigt hat. ABORTED X Der Kunde hat die Bestätigung widerrufen. EXPIRED X Der Kunde hat zu lange gewartet, um auf die CaB Checkout-Seite zu gelangen und sich dort einzuloggen oder neu zu registrieren. Der Status EXPIRED ist gebunden an den Status der entsprechenden PayTransaction. DECLINED X ClickandBuy hat die RPA oder die assoziierte PayTransaction abgelehnt. CANCELLED X Der Anbieter oder ClickandBuy haben die mit der RPA assoziierte PayTransaction storniert. EXHAUSTED X Die Limits der RPA wurden erreicht. 105