Classic Payment API SOPG ( xml-basiertes Protokoll) Dokumentation Versionshistorie Version Date Description Author 0.1 10.03.2013 Erster Entwurf Paul Kneidinger 0.2 20.03.2013 Details hinzugefügt und Matthias Vilsecker umstrukturiert 0.3 21.03.2013 In App Payment hinzugefügt Matthias Vilsecker 0.4 24.04.2013 Prüfung und weitere Ergänzung Natasa Jeremic 1.0 10.02.2013 Finale Version Natasa Jeremic 1.1 27.01.2014 Kleinere Änderungen Natasa Jeremic Mit technischen Fragen zur Implementierung wenden Sie sich bitte an integration@paysafecard.com 1
Inhaltsverzeichnis 1. Einführung 3 2. Funktionsübersicht Zahlung 3 2.1 Ablauf von Zahlungen 3 2.2 my paysafecard 4 2.2.1 KYC-Level 4 3. Über SOPG 4 3.1 Voraussetzungen 4 3.2 Umgang mit Fehlern 4 3.2.1 Beschreibung Fehlermeldungen 5 3.3 Inhaltstyp und Zeichensatz 5 4. Definition von paysafecard Systemen 5 4.1 Testumgebung (M-Test) 5 5. Technische Übersicht 5 6. Funktionsdetails und WSDL-Struktur 6 6.1 Funktionen 6 6.2 Zahlungsbenachrichtigung 7 6.2.1 Neuübermittlung der Zahlungsbenachrichtigung 8 6.3 Parameter 8 6.3.1 Beschreibung von Parametern 8 6.3.2 Einschränkungen 10 6.3.3 Disposition Status 10 6.4 Dispositionszeitfenster 10 6.5 Details Zahlungsfenster 11 6.5.1 Zahlungsfenster Desktop 11 6.5.2 Zahlungsfenster Mobilgeräte 11 6.6 Gebietsschema und Spracheinstellungen 11 7. Beispielzahlung 11 7.1 createdisposition 12 7.2 getmid (optional) 13 7.3 getcustomerpanel 13 7.4 pnurl Request 14 7.4.1 executedebit 14 8. Anhang A: Fehlercodes 15 9. Anhang B: In Zahlungsbenachrichtigungen unterstützte Ländercodes 18 10. Anhang C: In App Payment 18 10.1 Zahlungsfenster-Details für In App Payments 18 10.2 Technische Übersicht 19 11. Beispielintegration In App Payment 19 11.1 Unterstützte Betriebssysteme 19 11.2 Technische Übersicht: Beispielintegration 20 11.3 Implementierungsbeispiel 20 11.3.1 Initiieren der Zahlungskommunikation 20 11.3.2 Kommunikation zwischen Mobile App und Schließen des Client-Browsers 22 2
1. Einführung Dieses Dokument bietet einen detaillierten Überblick über Verwendung und Parameter des (SOPG) von paysafecard. Das Gateway ist ein SOAP-basierter XML-Webservice, der Zugriff auf das API-Clientfunktionen bietet, die mit jedem SOAP-kompatiblen Clientsystem genutzt werden können. Im ersten Kapitel finden Sie eine Funktionsübersicht des Zahlungsprozesses. Im Anschluss wird paysafecard SOPG im Detail vorgestellt. Es folgt eine Darstellung der Systeme von paysafecard sowie der technischen Details einschließlich einer vollständigen Beschreibung der Funktionen und Parameter. Am Ende des Dokumentes finden Sie neben einem Implementierungsbeispiel auch eine Einführung in das Thema In App Payments in Android Apps. 2. Funktionsübersicht Zahlung In jede Zahlung sind drei Parteien involviert: Ein Kunde, ein Geschäftspartner und das paysafecard Unternehmen ( PSC ). Zahlungen erfolgen als Zahlungstransaktionen oder Dispositionen, die durch eine Merchant Transaction ID (MTID) eindeutig gekennzeichnet sind und einen Wert enthalten, der als Betrag bezeichnet wird und üblicherweise der Geldsumme entspricht, mit der ein Kunde etwas erwirbt. 2.1 Ablauf von Zahlungen 3
2.2 my paysafecard my paysafecard ist: Ein Zahlungskonto, das paysafecard Kunden die Möglichkeit bietet, sich zu registrieren und mit Benutzername und Passwort Zahlungen vorzunehmen; sowie ein kundenfreundliches Instrument zur einfacheren Verwaltung von PINs, das einen klaren Überblick gestattet. Bezüglich der Integration ist es unerheblich, ob ein Kunde ein my paysafecard Konto zur Zahlung nutzt oder die PIN direkt eingibt. 2.2.1 KYC-Level Als Know your customer (KYC; deutsch: kenne deinen Kunden) wird eine Legitimationsprüfung von Neukunden zur Verhinderung von Geldwäsche bezeichnet, welche insbesondere für Kreditinstitute und Versicherungen vorgeschrieben ist. my paysafecard kennt zwei unterschiedliche KYC-Level: Simple Der Kunde hat die initiale Registrierung erfolgreich durchlaufen und eine Handynummer sowie eine E-Mail Adresse bestätigt. Full Möchte der Kunde seinen Verfügungsrahmen erweitern, kann er einen Identifikationsprozess durchlaufen, im Rahmen dessen folgende Dokumente verifiziert werden (der genaue Ablauf kann sich, je nach gesetzlichen Bestimmungen, von Land zu Land unterscheiden): von einer Regierungsbehörde ausgestelltes Ausweisdokument mit Foto und Name (z. B. Reisepass, Führerschein, Personalausweis etc.) oder Adressnachweis, z. B. ein Steuerbescheid oder die Rechnung eines Energieversorgers (Strom, Wasser, Gas, Kabel etc.) 3. Über SOPG Über das (SOPG) werden die Zahlungsfunktionalitäten von paysafecard als Webservice angeboten. Das Webservice basiert auf dem SOAP-Protokoll und kann, unabhängig von der Programmiersprache, von jedem SOAP-Client genutzt werden. Der komplette Zahlungsprozess wird zwischen dem System des Geschäftspartners und dem paysafecard SOPG abgewickelt. 3.1 Voraussetzungen Ein Geschäftspartner kann sich nur dann mit den Systemen von paysafecard verbinden, wenn folgende Voraussetzungen erfüllt sind: Er besitzt von paysafecard vergebene Login Daten (Benutzername/Passwort) Die IP-Adresse des Zahlungsservers wurde autorisiert (wird beim Versuch, auf den Dienst zuzugreifen, ein Fehler 403 ausgegeben, ist anzunehmen, dass die IP-Adresse noch nicht freigeschaltet wurde). 3.2 Umgang mit Fehlern Zu allen SOPG-Funktionen werden errorcode und resultcode ausgegeben. Der resultcode kann folgende Werte annehmen: 0 (erfolgreich), 1 (logisches Problem) oder 2 (technisches Problem). Generell gelten folgende Regeln: 1 deutet darauf hin, dass ein Problem mit den übermittelten Daten vorliegt (z. B. falsche Login Daten, Transaktionszeit abgelaufen etc.). Ein erneuter Versuch mit denselben Daten wird nicht erfolgreich sein. 2 (technisches Problem) bedeutet, dass der Service vorübergehend nicht erreichbar ist der Request kann erneut übermittelt werden. 4
3.2.1 Beschreibung Fehlermeldungen Bitte bedenken Sie, dass Fehlermeldungen für Kunden nur im paysafecard Zahlungsfenster angezeigt werden. In allen anderen Meldungen wird nur der Fehlercode angezeigt. %1, %2,... sind Platzhalter für verschiedene Werte, z. B. MTID, MID. Alle Fehlercodes und Meldungen finden Sie in Kapitel 8. 3.3 Inhaltstyp und Zeichensatz Bitte achten Sie beim Übermitteln von Requests darauf, dass im HTTP-Header folgende Werte gesetzt sind: Content-Type: text/xml;charset=utf-8 4. Definition von paysafecard Systemen 4.1 Testumgebung (M-Test) paysafecard stellt das paysafecard Testsystem (SOATEST), eine Testumgebung für die Integration neuer Geschäftspartner zur Verfügung. Die Integration neuer Geschäftspartner erfolgt zunächst in diesem Testsystem, wobei das Partner Integration and Support Team die neuen Partner unterstützt und die Abnahmetests durchführt. Nach Abnahme der Integration kann die Umstellung auf die Produktivsysteme erfolgen, die für den Geschäftspartner in folgenden Schritten abläuft: Umstellung auf Produktiv Login Daten (alle von paysafecard vergeben) Ersetzen der Service Endpoint URL Ersetzen der WSDL URL Alle Daten werden vom Merchant Service Center zur Verfügung gestellt. 5. Technische Übersicht 5
6. Funktionsdetails und WSDL-Struktur In diesem Dokument werden alle für den grundlegenden Zahlungsprozess erforderlichen Funktionen der SOPG WSDL-Struktur beschrieben. Bitte beachten Sie, dass der Vertrag viele weitere Funktionen umfasst. Alle erforderlichen Zahlungsparameter müssen angegeben und eine Übermittlung vorgenommen werden, auch wenn der Wert NULL bleibt. Benötigt das Webservice Framework eine WDSL in Echtzeit, laden Sie die SOPG WSDL von der WSDL URL herunter und stellen Sie diese in Ihrer lokalen Umgebung zur Verfügung. HINWEIS: Ein Abruf der WSDL von den paysafecard Servern in Echtzeit ist nicht möglich. 6.1 6.1 Funktionen Name der Beschreibung Funktion Der Geschäftspartner initiiert den Zahlungsprozess durch Übermittlung eines createdisposition Requests an paysafecard, durch das eine Disposition createdisposition auf dem Server angelegt wird. Der zulässige Maximalbetrag liegt bei 1.000,00 EUR (bzw. einem gleichwertigen Betrag in einer anderen Transaktionswährung). getcustomerpanel executedebit Ermöglicht dem Geschäftspartner, dem Kunden die Zahlungsseite für paysafecard Zahlungen anzuzeigen. Im Falle einer erfolgreichen paysafecard Zuweisung wird der Kunde zur okurl weitergeleitet. Klickt der Kunde auf Abbrechen, wird er zur nokurl weitergeleitet. Bucht das Geld von der paysafecard des Kunden ab. In diesem Schritt wird die Zahlung abgeschlossen, wenn die close Flag auf 1 gesetzt ist. Der Geschäftspartner kann die Transaktion bis zum Ende der Dispositionszeit offen halten (der Betrag wird in voller Höhe reserviert). Möchte der Geschäftspartner die Disposition schließen, ohne die Zahlung tatsächlich durchzuführen, muss die Funktion mit amount=0.00 aufgerufen werden. Request-Elemente username [erforderlich] password [erforderlich] mtid [erforderlich] subid [erforderlich] amount [erforderlich] currency [erforderlich] okurl [erforderlich] nokurl [erforderlich] merchantclientid [erforderlich] pnurl [erforderlich] clientip [erforderlich] dispositionrestrictions [erforderlich] shopid [erforderlich] shoplabel [erforderlich] mid [erforderlich] mtid [erforderlich] amount [erforderlich] currency [erforderlich] language [optional] locale [optional] username [erforderlich] password [erforderlich] mtid [erforderlich] subid [erforderlich] amount [erforderlich] currency [erforderlich] close [erforderlich] partialdebitid [optional] Response- Elemente mtid, subid, mid, resultcode, errorcode mtid, subid, resultcode, errorcode 6
Name der Funktion Beschreibung Request-Elemente Response- Elemente getmid (optional) Der Geschäftspartner kann die der jeweiligen Währung zugewiesene MID (einzigartige ID des Geschäftspartners) abfragen. username [erforderlich] password [erforderlich] currency [erforderlich] username [erforderlich] password [erforderlich] currency [erforderlich] getserialnumbers (optional) Ruft den Disposition Status ab und prüft, ob dieser dem erwarteten Status entspricht, bevor die nächste Funktion aufgerufen wird. username [erforderlich] password [erforderlich] mtid [erforderlich] subid [erforderlich] currency [erforderlich] mtid, subid, resultcode, errorcode, amount, currency, dispositionstate, serialnumbers modifydisposition Value (optional) Möglichkeit, den Betrag der ursprünglichen Disposition zu reduzieren. username [erforderlich] password [erforderlich] mtid [erforderlich] subid [erforderlich] amount [erforderlich] currency [erforderlich] mtid, subid, resultcode, errorcode 6.2 Zahlungsbenachrichtigung Die Zahlungsbenachrichtigung wird verwendet, um den Geschäftspartner nach der paysafecard Zuweisung unabhängig vom Kundenverhalten zu informieren. Dieser Service stellt sicher, dass Dispositionen vor dem Aufladen des Kundenkontos abgeschlossen werden können und ist deshalb ausgesprochen empfehlenswert, um unvollständige Transaktionen zu verhindern. API-Parameter Beschreibung Ausgabe-Parameter pnurl Eine Zahlungsbenachrichtigung wird nur nach erfolgreicher paysafecard Zuweisung übermittelt. Diese Benachrichtigung wird zusätzlich zur Weiterleitung zur okurl versandt. Im Falle technischer Anwendungsfehler auf Seiten des Geschäftspartners wird die Zahlungsbenachrichtigung erneut übermittelt. mtid eventtype (ASSIGN_CARDS is returned) serialnumbers currency disposition amount cardtypeld 1 Merchant Response- Elemente HTTP 200 1 Der Parameter bietet eine Kombination aus dem Standard-ISO-Ländercode (des Landes, in dem paysafecard verkauft wurde) und der ID des Kartentyps (definiert den paysafecard Typ, z. B. paysafecard junior). Weitere Informationen hierzu entnehmen Sie bitte Anhang B: In Zahlungsbenachrichtigungen unterstützte Ländercodes. 7
6.2.1 Wiederholte Zustellung der Zahlungsbenachrichtigung Im Falle technischer Fehler (z. B. Socket Timeout) oder Anwendungsfehler (z. B. HTTP Statuscode 500) wird die Zahlungsbenachrichtigung in regelmäßigen Abständen erneut übermittelt, bis eines der folgenden Kriterien erfüllt ist: Die Zahlungsbenachrichtigung wurde erfolgreich zugestellt (d. h. Zahlungsserver antwortet mit HTTP-Statuscode 200) Die maximale Anzahl von Wiederholungsversuchen wurde erreicht (aktuelle Konfiguration: 5 Wiederholungsversuche). 6.3 Parameter 6.3.1 Parameter-Beschreibung username individueller Konto-Benutzername von paysafecard zur Authentifizierung zur Verfügung gestellt password individuelles Konto-Passwort von paysafecard zur Authentifizierung bereitgestellt mtid (eindeutige) Transaktions-ID, eindeutiger Identifikator für jede Disposition. max. Länge: 60 Zeichen empfohlen: bis zu 20 Zeichen durch Geschäftspartner bereitgestellt Nur folgende Werte zulässig: A-Z, a-z, 0-9 sowie - (Bindestrich) und _ (Unterstrich) Beispiel: 3516-6s4dfsad41 subid zwingend erforderlicher Parameter, sofern nichts anderes vereinbart wurde, ist dieser Wert leer zu lassen. Sogenannte reporting criteria (Reportingkriterien) bieten die Möglichkeit, Transaktionen zu klassifizieren max. Länge: 8 Zeichen (Groß-/Kleinschreibung) Vereinbarung mit paysafecard erforderlich Beispiel: shop1 amount Dispositionsbetrag Angefragter Betrag darf 1.000,00 EUR (bzw. einen gleichwertigen Betrag in einer anderen Transaktionswährung) nicht überschreiten max. 11 Zeichen vor - exakt 2 Zeichen nach dem Dezimalpunkt Verwenden Sie einen Punkt als Dezimaltrennzeichen Beispiel: 100.00 currency Dispositionswährung max. Länge: 3 Zeichen, alles Großbuchstaben ISO-Währungscode Beispiel: EUR pnurl Zahlungsbenachrichtigungs-URL, über die paysafecard den Geschäftspartner informiert, sobald eine paysafecard erfolgreich einer Disposition zugewiesen wurde (weitere Details in Kapitel 6.2). URL muss absolut und URL-kodiert sein, weil sie als Parameter übermittelt wird URL muss vom Geschäftspartner definiert werden max. Länge: 765 Zeichen okurl die URL, zu der Kunden von paysafecard weitergeleitet werden, sobald sie ihre paysafecard PINs erfolgreich zugewiesen haben. Der Geschäftspartner kann Informationen in die URL einbinden. URL muss absolut und URL-kodiert sein, weil sie als Parameter übermittelt wird max. Länge: 765 Zeichen nokurl Die URL, zu der Kunden von paysafecard weitergeleitet werden, wenn Sie im paysafecard Zahlungsfenster auf Abbrechen klicken. URL muss absolut und URL-kodiert sein, weil sie als Parameter übermittelt wird max. Länge: 765 Zeichen 8
HINWEIS: Die okurl, nokurl und optional die pnurl sind unbedingt URL-kodiert (man spricht auch von prozentkodiert) zu übermitteln. Geschieht dies nicht, kann es zu einer falschen Weiterleitung des Kunden zur Bestätigungsseite sowie möglicherweise zu einem Fehlschlagen der Zahlung kommen. merchantclientid eindeutiger Endkundenidentifikator (z. B. die eindeutige ID, mit der der Endkunde in der Datenbank des Geschäftspartners registriert ist). Falls Sie E-Mail-Adressen verwenden, verschlüsseln Sie diese bitte. Im Rahmen von Promotions prüft paysafecard die clientid, um Mehrfacheinlösungen zu verhindern. HINWEIS: Verwenden Sie aus Sicherheitsgründen nicht den registrierten Benutzernamen des Kunden max. Länge: 50 Zeichen Beispiel: client123 clientip Die IP-Adresse des paysafecard Kunden. shopid Kennung des Shops, von dem der Request ausgeht. Wird meist von Payment Service Providern verwendet, die auch als Proxy für andere Zahlungsmethoden agieren. max. Länge: 60 Zeichen Empfohlen: bis zu 20 Zeichen durch Geschäftspartner bereitgestellt Zulässig sind nur: A-Z, a-z, 0-9 sowie - (Bindestrich) und _ (Unterstrich) Beispiel: 2568-B415rh_785 shoplabel Label oder URL des Webshops, von dem der Request ausgeht, steht in Zusammenhang mit der shopid. Wird am wahrscheinlichsten von Payment Service Providern verwendet, die auch als Proxy für andere Zahlungsmethoden agieren. Max. Länge: 60 Zeichen Beispiel: www.foodstore.com mid Merchant ID, eindeutige ID des Geschäftpartners/Währungs-Kombination. 10 Zeichen lang von paysafecard zur Verfügung gestellt Beispiel: 1000001234 dispositionstate aktueller Status der Disposition (weitere Details in Kapitel 6.3.3). serialnumbers Seriennummer(n) vom Kunden zugewiesener paysafecard PINs, nach Eingabe der PINs im paysafecard Zahlungsfenster (Werte durch Semikolon getrennt). currency: ISO-Währungscode disposition amount: zu dieser Disposition reservierter Betrag auf der paysafecard des Kunden cardtypeid: paysafecards werden in verschiedene Kartentypen eingeteilt, z. B. junior_paysafecard; adult_paysafecard; inhouse_paysafecard Beispiele: 0000000001200000;EU R;7.50;00002; 0000000001300000;EU R;5.50;00002; close Die Close Flag einer Disposition kann auf 0 oder 1 gesetzt werden und zeigt an, ob weitere Aktivitäten durchgeführt werden oder nicht. 0 [Transaktion nicht schließen] 1 [Transaktion schließen, dies ist die letzte Abbuchung] partialdebitid über diesen Parameter können Teilzahlungen klassifiziert werden. resultcode Ergebniscode der Funktion (Details im Kapitel Ergebniscodes). errorcode Fehlercode der Funktion (Details im Kapitel Fehlercodes). dispositionrestrictions Dispositionseinschränkungen können von Geschäftspartnern definiert werden, um Zahlungstransaktionen im Rahmen ihrer individuellen Anforderungen zu begrenzen. Details in Kapitel 6.3.2. Mehrere Wiederholungen möglich Jede Einschränkung besteht aus einem key und einem value : key - der Schlüssel der Einschränkung value - der Wert der Einschränkung 9
6.3.2 Einschränkungen Bitte übermitteln Sie mit dem API-Request createdisposition einen Ländercode (ISO 3166-1), um die Zahlung auf das gewünschte Land zu beschränken. Schlüssel Beispielwert mögliche Werte Beschreibung COUNTRY DE alle Länder, in denen paysafecard erhältlich ist (Beispiel: FR, ES,...) Beschränkt die Durchführung einer Zahlung exklusiv auf Deutschland. Als Wert können Ländercodes gemäß ISO 3166-1 angegeben werden. Folgende Beschränkungen sind für paysafecard Zahlungen über ein paysafecard Konto (my paysafecard) verfügbar: Schlüssel Beispielwert mögliche Werte Beschreibung MIN_AGE 18 muss einen positiven Zahlenwert enthalten Beschränkung auf my paysafecard Kontoinhaber mit einem Mindestalter von 18 Jahren. MIN_KYC_ LEVEL FULL SIMPLE oder FULL Beschränkung auf my paysafecard Kontoinhaber mit mindestens angegebenem Status, hier FULL. 6.3.3 Disposition Status One letter code Meaning Description R Created Die Disposition wurde erfolgreich angelegt. Geschieht in den kommenden 30 Minuten nichts, wird der Disposition Status durch paysafecard auf X gesetzt. S Disposed Die paysafecard des Kunden wurde der Disposition erfolgreich zugewiesen. Der Geschäftspartner kann executedebit ausführen; es wurden noch keine Abbuchungen vorgenommen. O Consumed Die finale Abbuchung mit close=1 wurde ausgeführt; keine weiteren Abbuchungen möglich. L Cancelled Die Disposition wurde vom Kunden aktiv abgebrochen. X Expired Das Zeitfenster für die Disposition ist abgelaufen (entweder bevor eine paysafecard zugewiesen oder bevor executedebit aufgerufen wurde). E Debited Teilabbuchung: Die Disposition ist noch offen, weitere Abbuchungen möglich. 6.4 Dispositionszeitfenster Sobald eine Disposition in Status S ( DISPOSED ) vorliegt, müssen die Geschäftspartner innerhalb eines vorgegebenen Zeitraumes ihre Abbuchungen vornehmen (Dispositionszeit). Das Zeitfenster kann für jede MID gesondert konfiguriert werden. Mit Ende der Dispositionszeit läuft die Disposition automatisch ab, der auf der paysafecard des Kunden reservierte Betrag wird wieder verfügbar. Außerdem werden alle angelegten, jedoch nicht erfolgreich abgebuchten Dispositionen auf EXPIRED gesetzt. HINWEIS: Diese Jobs sind nur auf den paysafecard Produktivservern aktiv. 10
6.5 Details Zahlungsfenster 6.5.1 Zahlungsfenster Desktop Das paysafecard Zahlungsfenster kann in einem Popup-Fenster oder alternativ in einem iframe angezeigt werden. Um sicherzustellen, dass das gesamte Zahlungsfenster für den Benutzer sichtbar ist, bieten Sie bitte stets die Möglichkeit zum vertikalen Scrollen oder für dynamisches Skalieren. Die Breite ist auf 600 px fixiert Die Höhe ist auf 840 px fixiert 6.5.2 Zahlungsfenster Mobilgeräte Das paysafecard Zahlungsfenster ist für Mobilgeräte optimiert. Verwendet ein Kunde ein Gerät mit einer Auflösung unter 600 px wird ein optimiertes Zahlungsfenster angeboten. Dasselbe gilt, wenn der eingebettete iframe schmaler als 600 px ist. HINWEIS: Der iframe zur Einbettung des Desktop-Zahlungsfenster muss mindestens 600 px breit sein. Anderenfalls wird die mobile Version des Zahlungsfensters angezeigt. 6.6 Gebietsschema- und Spracheinstellungen Zur Gewährleistung der Rückwärtskompatibilität geben alle Sprachparameter weiterhin dieselben Ergebnisse aus wie in Vorgängerversionen der API, alle Sprachen werden jedoch automatisch in Gebietsschemata umgewandelt. Sprache und Gebietsschema des Zahlungsfensters werden grundsätzlich durch folgende Regel bestimmt: 1. Hat der Kunde das Zahlungsfenster schon einmal besucht? Abrufen des Gebietsschemas aus dem gesetzten Cookie. 2. Ableiten des Gebietsschemas aus der IP-Adresse des Kunden 1. 3. Verwenden des Wertes aus dem Gebietsschema-Parameter. 4. Verwenden des Wertes aus dem Sprach-Parameter. 5. Abrufen des Gebietsschemas aus dem Browser-Header. 6. Verwenden des Fallback-Gebietsschemas (de_de). Es ist deshalb nicht erforderlich, ein Gebietsschema-Parameter zu bestimmen. 7. Beispielzahlung In diesem Kapitel wird ein Testszenario mit Beispieldaten vorgestellt. In der Praxis wird der Ablauf von Geschäftspartner zu Geschäftspartner variieren, je nachdem, ob eine oder mehrere Abbuchungen oder Statusabfragen durchgeführt werden. Verwenden Sie für Ihre Tests nicht die Daten aus diesem Beispiel! Jeder Geschäftspartner erhält zum Testen einen einheitlichen Testdatensatz. 1 paysafecard nutzt eine GeoIP-Prüfung. 11
7.1 createdisposition Der Geschäftspartner initiiert den Zahlungsprozess durch Versenden eines createdisposition Request. Beispiel-Request: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:urn= urn:pscservice > <soapenv:header/> <soapenv:body> <urn:createdisposition> <urn:username>user</urn:username> <urn:password>password</urn:password> <urn:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</urn:mtid> <!--Zero or more repetitions:--> <urn:subid></urn:subid> <urn:amount>10.00</urn:amount> <urn:currency>eur</urn:currency> <urn:okurl>http%3a%2f%2fwww%2epaysafecardokurl%2ecom</urn:okurl> <urn:nokurl>http%3a%2f%2fwww%2epaysafecardnokurl%2ecom</urn:nokurl> <!--Optional:--> <urn:merchantclientid>cid_919191</urn:merchantclientid> <!--Optional:--> <urn:pnurl> http%3a%2f%2fwww%2emerchantpnurl%2ecom </urn:pnurl> <!--Zero or more repetitions:--> <urn:dispositionrestrictions> <urn:key>country</urn:key> <urn:value>fr</urn:value> </urn:dispositionrestrictions> <urn:dispositionrestrictions> <urn:key>min_age</urn:key> <urn:value>18</urn:value> </urn:dispositionrestrictions> <!--Optional:--> <urn:shopid>3516-6s4dfsad41</urn:shopid> <!--Optional:--> <urn:shoplabel>www.foodstore.com</urn:shoplabel> </urn:createdisposition> </soapenv:body> </soapenv:envelope> Beispiel-Response: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ > <soapenv:body> <ns1:createdispositionresponse xmlns:ns1= urn:pscservice > <ns1:createdispositionreturn> <ns1:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</ns1:mtid> <ns1:mid>1000001234</ns1:mid> <ns1:resultcode>0</ns1:resultcode> <ns1:errorcode>0</ns1:errorcode> </ns1:createdispositionreturn> </ns1:createdispositionresponse> </soapenv:body> </soapenv:envelope> </soapenv:body> </soapenv:envelope> 12
7.2 getmid (optional) Mit getmid kann der Geschäftspartner die der angefragten Währung zugewiesene eindeutige Merchant ID (MID) abrufen. Beispiel-Request: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:urn= urn:pscservice > <soapenv:header/> <soapenv:body> <urn:getmid> <urn:username>user</urn:username> <urn:password>password</urn:password> <urn:currency>eur</urn:currency> </urn:getmid> </soapenv:body> </soapenv:envelope> Beispiel-Request: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ > <soapenv:body> <ns1:getmidresponse xmlns:ns1= urn:pscservice > <ns1:getmidreturn> <ns1:currency>eur</ns1:currency> <ns1:mid>1000001234</ns1:mid> <ns1:resultcode>0</ns1:resultcode> <ns1:errorcode>0</ns1:errorcode> </ns1:getmidreturn> </ns1:getmidresponse> </soapenv:body> </soapenv:envelope> 7.3 getcustomerpanel createdisposition wurde erfolgreich ausgeführt. Der Kunde kann nun zum paysafecard Zahlungsfenster weitergeleitet werden, um der Disposition Karten zuzuweisen. Beispiel-URL Testsystem: https:// customer.test.at.paysafecard.com/psccustomer/getcustomerpanelservlet Beispiel-URL Produktivsystem: https:// customer.cc.at.paysafecard.com/psccustomer/getcustomerpanelservlet?mid=1000001234 &mtid=18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4 &amount=10.00 ¤cy=eur Beispiel Eingabeparameter: PIN: 0000 0000 1234 5678 Terms of Use: <checkbox, default unchecked> 13
7.4 pnurl request Das paysafecard System übermittelt ein HTTP POST Request an das System des Geschäftspartners (pnurl), um dieses über die erfolgreiche Zuweisung der paysafecard PINs des Kunden zu informieren. Beispiel-URL: http://www.merchantpnurl.com/notifyme?mtid=3516-6s4dfsad41 &eventtype=assign_cards &serialnumbers=0000000001200000;eur;100.00;de00002 Beispiel-Response: HTTP 200 7.4.1 executedebit Nachdem der Kunde der Disposition erfolgreich Karten zugewiesen hat, führt der Geschäftspartner die Abbuchung durch und belastet die paysafecard des Kunden mit dem jeweiligen Betrag. Beispiel-Request: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:urn= urn:pscservice > <soapenv:header/> <soapenv:body> <urn:executedebit> <urn:username>user</urn:username> <urn:password>password</urn:password> <urn:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</urn:mtid> <!--Zero or more repetitions:--> <urn:subid></urn:subid> <urn:amount>10.00</urn:amount> <urn:currency>eur</urn:currency> <urn:close>1</urn:close> </urn:executedebit> </soapenv:body> </soapenv:envelope> Beispiel-Response: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ > <soapenv:body> <ns1:executedebitresponse xmlns:ns1= urn:pscservice > <ns1:executedebitreturn> <ns1:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</ns1:mtid> <ns1:subid/> <ns1:resultcode>0</ns1:resultcode> <ns1:errorcode>0</ns1:errorcode> </ns1:executedebitreturn> </ns1:executedebitresponse> </soapenv:body> </soapenv:envelope> 14
8. Anhang A: Fehlercodes Können Sie einen Fehlercode nicht in der Liste finden, wenden Sie sich bitte an integration@paysafecard.com Beschreibung von resultcodes (Ergebniscodes): Name Ergebnis Beschreibung resultcode errorcode 0 : erfolgreich 1 : logisches Problem 2 : technisches Problem Enthält eine Fehlernummer, wenn der resultcode nicht gleich 0 ist. Allgemeine Meldungen Fehler: 0001-0141 1=Keine Daten ausgewählt. 2=%1 ist kein numerischer Wert. 3=Kein Inhalt in Pflichtfeld %1. 4=Dezimalfeld mit Name %1 und Wert %2 enthält keinen Dezimalpunkt. 5=Dezimalfeld mit Name %1 und Wert %2 enthält keine Ziffern vor dem Dezimalpunkt. 6=Dezimalfeld mit Name %1 und Wert %2 enthält zu viele Ziffern vor dem Dezimalpunkt (max. zulässig: %3). 7=Dezimalfeld mit Name %1 und Wert %2 enthält zu wenige Ziffern nach dem Dezimalpunkt (muss %3 entsprechen). 8=Dezimalfeld mit Name %1 und Wert %2 enthält zu viele Ziffern nach dem Dezimalpunkt (max. zulässig: %3). 9=Dezimalfeld mit Name %1 und Wert %2 enthält keine Zahl im Format N.M (wobei N gleich 1 bis %3 Ziffern und M genau %4 Ziffern entspricht und beide, M und N, numerische Werte sind). 10=Dezimalfeld mit Name %1 und Wert %2 enthält keine Ziffern nach dem Dezimalpunkt (muss mindestens 1 und höchstens %3 entsprechen). 11=Dezimalfeld mit Name %1 und Wert %2 darf nicht negativ sein. 12=Dezimalfeld mit Name %1 und Wert %2 enthält keine Zahl im Format N.M (wobei N gleich 1 bis %3 Ziffern und M gleich 1 bis %4 Ziffern ist und beide, M und N, numerische Werte sind). 13=Kein Inhalt im Dezimalfeld mit Name %1. 14=Verarbeitung von maximal %1 Objekten pro Transaktion. 15=Keine Antwort auf Sicherheitsfrage angegeben. 16=Sicherheitsfrage falsch beantwortet. 17=Antwort auf Sicherheitsfrage enthält ungültige Zeichen. 20=Keine Sicherheitsfrage angegeben. 21=Sicherheitsfrage mit Wert %1 ist zu lang (max. zulässig: %2 Zeichen). 50=Keine Merchant ID angegeben. 51=Merchant ID mit Wert %1 ist zu lang (max. zulässig: %2 Zeichen). 55=Keine Merchant Transaction ID angegeben. 56=Merchant Transaction ID mit Wert %1 ist zu lang (max. zulässig: %2 Zeichen). 60=Keine nokurl angegeben. 65=Keine okurl angegeben. 75=Keine Seriennummer angegeben. 76=Seriennummer mit Wert %1 ist zu lang (max. zulässig: %2 Zeichen). 77=Seriennummer %1 ist kein numerischer Wert. 80=Kartenstatus %1 ungültig. 81=Übermittelter Kartenstatus %1 in Feld %2 entspricht nicht dem erwarteten Kartenstatus %3. 85=Kartentyp %1 ungültig. 90=Debitstatus %1 ungültig. 95=Disposition Status %1 ungültig. 96=Übermittelter Disposition Status %1 in Feld %2 entspricht nicht dem erwarteten Disposition Status %3. 15
120=Close Debit-Flag %1 ist ungültig (muss 0 oder 1 sein). 125=Keine Währung angegeben. 126=Währung mit Wert %1 hat unzulässige Länge (muss 3 Zeichen lang sein). 140=Kein Währungsname angegeben. 141=Währungsname mit Wert %1 ist zu lang (max. zulässig: %2 Zeichen). # Allgemeine Meldungen Erfolgsmeldungen 0601-0603 601=Befehl erfolgreich ausgeführt. 602=Befehl erfolgreich ausgeführt; keine Daten gefunden. 603=Befehl erfolgreich ausgeführt; weitere Daten entsprechen Filterkriterien (für weniger Suchergebnisse Filterkriterien anpassen). # Kartenmeldungen Fehlermeldungen: 1001-1600 1004=Karte mit Seriennummer %1 in unerwartetem Status %2. Erwartet wurde %3. 1005=Karte mit Seriennummer %1 hat keinen Ort %3 sondern %2. 1006=Karte mit Seriennummer %1 ist nicht %2 zugewiesen. 1007=Karte mit Seriennummer %1 existiert nicht. 1008=Zugriff verweigert. 1009=%1 dürfen keine Karten zugewiesen sein. 1012=Kartenstatus %1 ist für diesen Request nicht verfügbar; erwartet wurde Kartenstatus %2. 1015=Zugriff aufgrund wiederholter Verletzung von Zugriffsrechten verweigert. 1020=Sicherheitsantwort 1 und Sicherheitsantwort 2 unterscheiden sich. 1025=Ungültiger Kartenstatus. Erwarteter Status: GENERATED. 1026=Anzahl gedruckter Exemplare ungültig; Kartenstatus wird auf INVALID gesetzt. 1029=Geben Sie Sicherheitsfrage, Antwort und Antwortwiederholung ein, um Ihre Sicherheitsfrage festzulegen. 1035=Der Kartenstatus mindestens einer im Rahmen dieser Anfrage verwendeten Karten ist ungültig. 1046=Auf dieser Karte ist derzeit kein Guthaben verfügbar; im Falle reservierter Beträge. 1049=Mindestens eine der verwendeten PINs ist ungültig. 1050=Karte existiert nicht. # Zahlungsmeldungen Fehlermeldungen: 2001-2600 2001=Transaktion (%1/%2) bereits vorhanden. Bitte wenden Sie sich an Ihren Webshop. 2002=Transaktion (%1/%2) nicht vorhanden. Bitte wenden Sie sich an Ihren Webshop. 2003=Transaktion (%1/%2) in ungültigem Status %3; erwartet wurde %4. 2004=Guthaben reicht zur Zahlung nicht aus; offener Betrag entspricht %1. 2006=Transaktionswährung %1 ungültig für Transaktion (%2/%3). Bitte wenden Sie sich an Ihren Webshop. 2007=Betrag %1 für verwendete Karte ungültig. 2008=Betrag %1 übersteigt Kartenguthaben. 2009=Betrag %1 für verwendete Transaktion (%2/%3) ungültig. Bitte wenden Sie sich an Ihren Webshop. 2010=Ungenügender Dispositionsbetrag %1 für Transaktion (%2/%3). 2011=Währung %1 ist für diese Transaktion ungültig; erwartet wird %2. 2012=Zahlungstransaktion fehlgeschlagen. 2013=Fehler beim Finden der Transaktion: %1. 2014=Für diese Zahlungstransaktion wurde keine Disposition erstellt. 2015=Zahlungstransaktion fehlgeschlagen. 2016=Fehler beim Finden des Merchant: %1. 2017=Transaktion (%1/%2) in ungültigem Status %3; erwartet wurde %4 oder %5. 2018=MicroDebits für Transaktion (%1/%2) sind nicht fortlaufend. 2019=Kein MicroDebit für Transaktion (%1/%2) vorhanden. 2020=Geschäftstyp der Transaktion (%1/%2) ist %3. Betrag kann nicht geändert werden. 2021=Betrag %1 für verwendete Transaktion (%2/%3) ungültig. Mindesttransaktionsbetrag liegt bei %4. 2022=Transaktion (%1/%2) wurden keine Karten zugewiesen. 2023=Geschäftstyp der Transaktion (%1/%2) ist %3; erwartet wurde: %4. Bitte wenden Sie sich an Ihren Webshop. 2024=Abbuchung kann nicht vorgenommen werden: Geschäftstyp der Transaktion (%1/%2) ist %3. 2025=Kein Transaktionsbetrag angegeben. Bitte wenden Sie sich an Ihren Webshop. 2026=Transaktionsbetrag %1 ist kein numerischer Wert. Bitte wenden Sie sich an Ihren Webshop. 2027=Transaktionsbetrag %1 ist ungültig. Bitte wenden Sie sich an Ihren Webshop. 2028=Geschäftstyp %1 ist für die Transaktion ungültig. 2029=Bei dieser Transaktion ist ein Fehler aufgetreten der Betrag muss größer null sein. 2039=Ungültige Einschränkungsparameter. 2044=customerdetailsrequested {0} ist ungültig (muss 0 oder 1 sein). 2623=Shop ID enthält mehr als 60 Zeichen. 2624=Shop Label enthält mehr als 60 Zeichen. 16
# Zahlungsmeldungen Erfolgsmeldungen: 2601-2900 2601=Zahlung erfolgreich abgeschlossen. 2602=Befehl erfolgreich ausgeführt. Keine Transaktionen gefunden. # Master-Referenz Fehlermeldung: 3001-3600 3001=Merchant %1 ist nicht aktiv. Bitte wenden Sie sich an Ihren Webshop. 3002=Währung %1 ist für Merchant %2 nicht gültig. Bitte wenden Sie sich an Ihren Webshop. 3003=Merchant %1 nicht vorhanden. Bitte wenden Sie sich an Ihren Webshop. 3006=Merchant akzeptiert Kartentyp %1 nicht. 3007=Merchant %1 hat Zeitfenster für Abbuchung der Transaktion überschritten. 3012=Merchant %1 hat Zeitfenster für Micropayment überschritten. 3013=Merchant %1 ist bereits vorhanden. 3014=Reporting Criterion %1 für Merchant %2 existiert nicht. 3015=Reporting Criterion %1 für Merchant %2 hat Status %3; erwartet wurde %4 oder %5. # Feature-Meldungen: 3901-4000 3901=Feature mit Primärschlüssel (%1 %2 %3) nicht gefunden. 3902=Benutzer %1 hat keine Zugriffsberechtigung für Feature %2. # Technische Meldungen Merchant API - Fehlermeldungen: 4001-4600 4001=SSL-Fehler. 4002=Ungültige Funktionsanfrage. 4003= Überschreitung des maximalen Dispositionsbetrags (1.000,00 EUR oder gleichwertiger Betrag in anderer Transaktionswährung) 4004=Ungültiger Proxy-Request. 4005=Verbindungsfehler. 4006=Unerwartete Antwort vom Server. 4007=Undefinierter Fehler das sollte nicht vorkommen. 4008=Fehlermeldung vom Backend. 4010=Fehler beim Öffnen der Konfigurationsdatei. 4011=Konfigurationsdatei ist keine regulär lesbare Datei. 4012=Fehlerhafte Syntax in der Konfigurationsdatei. 4013=Fehlerhafter Wert in der Konfigurationsdatei. 4014=Fehlerhafte HTTP-Antwort vom API-Proxy: %1. # Technische Fehlermeldungen: 5001-5500 5001=Allgemeiner technischer Fehler. 5002=MAC-Test. # SOPG-spezifische Fehlermeldungen: 10000-20001 10003= Fehler HTTPS-Request 10004= Allgemeiner technischer Fehler 10005= Allgemeiner technischer Fehler 10006= PIN-Validierung fehlgeschlagen 10007= Unerwarteter Fehler 10008= Authentifizierung fehlgeschlagen 10010= Zu spät für cancelpayment 10011= Nicht genügend Guthaben 10012= Kein Guthaben 10013= Karte nicht aktiv 10014= Methode für SOPG-User nicht zulässig 10015= Währung für SOPG-User nicht gültig 17
9. Anhang B: In Zahlungsbenachrichtigungen unterstützte Ländercodes Als zusätzlicher Informationsparameter bildet der Ländercode (des Landes, in dem paysafecard verkauft wird) einen Bestandteil des Standard API-Requests der Zahlungsbenachrichtigung. Der Parameter cardtypeid in der Zahlungsbenachrichtigung enthält eine Kombination aus dem Standard-ISO- Ländercode und der ID des Kartentyps. Ausnahme: Manche Karten sind keinem bestimmten Land zugeordnet. Deshalb wird hier kein Ländercode übermittelt. Grundlegender pnurl Response mtid=<mtid> &eventtype=<eventtype> &serialnumbers=<serialnr1>;<currency1>;<amount1>;<cardtyp1>; <serialnr2>;<currency2>;<amount2>;<cardtype2>; BeispielpnUrl Response mtid=123456 &eventtype=assign_cards &serialnumbers=0000000001200000; EUR; 50.00; XX00004; 0000000001200001; EUR; 50.00; XX00004 10. Anhang C: In App Payment Dieses Kapitel beschreibt, wie paysafecard Zahlungen mit unseren Beispielcodes aus dem Download-Bereich in eine Android App integriert werden können. 10.1 Zahlungsfenster-Details für In App Zahlungen Für einen reibungslosen Zahlungsvorgang empfehlen wir dringend, das Zahlungsfenster in die Handy-App einzubetten. HINWEIS: Bitte schließen Sie das paysafecard Zahlungsfenster nach Erhalt der Zahlungsbenachrichtigung. Das ist erforderlich, weil Kunden bei einer Weiterleitung außerhalb der App nicht automatisch in die App zurückgeleitet werden. 18
10.2 Technische Übersicht 11. Beispielintegration In App Payment In diesem Kapitel wird die Beispielintegration mit JSON Requests beschrieben. 11.1 Unterstützte Betriebssysteme Folgende Android-Versionen sind getestet und werden unterstützt: Android 2.1-update1 Android 2.2 Android 2.3.1 Android 2.3.3 Android 3.0 Android 3.1 Android 3.2 Android 4.0 19
11.2 Technische Übersicht: Beispielintegration JSON:initiatePayment Der Geschäftspartner initiiert die Zahlung auf dem eigenen Backend-Server. JSON:checkTransaction Die Handy App fragt den Status der erfolgreichen Zahlungsdisposition beim Backend-Server des Geschäftspartners ab. Die Handy App muss informiert werden, sobald die Zahlungsbenachrichtigung eingegangen ist. HINWEIS: Die Zahlungsbenachrichtigung wird nur im Falle einer erfolgreichen Zuweisung übermittelt. 11.3 Implementierungsbeispiel Diese Beispiele basieren auf einem ANDROID OS. Der Code der Demo Android App und des Webshop Servers hilft Ihnen das Beispiel zu verstehen. In den folgenden Schritten werden wir die interessantesten Codestellen der Referenzimplementierung beschreiben. 11.3.1 Initiieren der Zahlungskommunikation zwischen App und Backend-Server des Geschäftspartners Folgende Schritte müssen in der Android App durchgeführt werden, damit Zahlungen mit paysafecard durchgeführt werden können: 1. Der User initiiert die Zahlung in einer Android App (z. B. um ein bestimmtes Spiel zu spielen). 2. Die Applikation des Geschäftspartners initiiert über den Backend-Server die Zahlung (Anlegen einer Disposition im paysafecard System). 3. Sobald die Disposition angelegt ist, sollte das paysafecard Zahlungsfenster geöffnet werden. 4. Der Benutzer gibt die paysafecard PIN ein und weist der Disposition eine Karte zu. Nach der erfolgreichen Zuweisung übernimmt die App die Kommunikation mit dem Backend-Server des Geschäftspartners, der im letzten Schritt ein executedebit Request übermittelt, um die paysafecard des Kunden zu belasten. 20
11.3.1.1 Code Beispiele: Nach Auslösen von PaySafeCardActivityWithBrowser (siehe Code) wird die Methode handleintent aufgerufen. public void handleintent() { final Intent intent = getintent(); } if (PaySafeCard.ACTION_PAY.equals(intent.getAction())) { handlepayaction(intent); } else if (Intent.ACTION_VIEW.equals(intent.getAction())) { handlebrowsercallbackaction(intent); } Diese Methode handelt Intents mit unterschiedlichen Aktionen (ACTION_PAY vs. ACTION_VIEW), und führt in Abhängigkeit von diesen Aktionen die nächsten Schritte in der App durch. Beim ersten Start der Activity übermittelt die Eltern-Activity die Aktion ACTION_PAY, die folgenden Request initiiert: Beispiel-Request: private void handlepayaction(final Intent intent) { payment = (Payment) intent.getparcelableextra(paysafecard.extra_ PAYMENT); pscbean = PscBean.from(payment); initpaymenttask = new InitPaymentAsyncTask(ConnectorFactory.instance().get()); initpaymenttask.bindcontext(this); initpaymenttask.registerlistener(new InitPaymentResultListener()); initpaymenttask.execute(pscbean); } Die Methode HandlePayAction legt über den Backend-Server des Geschäftspartners eine neue Disposition an. Diese Aktivität erfolgt im Rahmen einer separaten AsyncTask. Die Methode InitPaymentResultListener informiert über die erfolgreiche Anlage oder einen Fehler. Wurde die Disposition erfolgreich angelegt, wird die Callback-Methode onresult im InitPaymentResultListener aufgerufen: public void onresult(final String result) { final Intent browserintent = PaySafeCardActivityWithBrowser.createBrowserIntent(Uri. parse(result)); isbrowserstarted = true; startactivity(browserintent); } Diese Methode startet und öffnet ein neues Browserfenster mit dem paysafecard Zahlungsfenster für Mobilgeräte. Sehen Sie sich für ein besseres Verständnis den vollständigen Code für folgende Klassen an: InitPaymentResultListener, InitPaymentAsyncTask und InitPaymentResultListener. 21
11.3.1.2 Request-Beispiele Für die Kommunikation zwischen einer Android App und dem WSDL-basierten SOPG Webservice haben wir einen einfachen, REST-basierten Backend-Server implementiert. Die Demo App kommuniziert also nur direkt mit einem REST-basierten Backend Server. Die Kommunikation erfolgt über schlanke JSON-Objekte. HINWEIS: Dies ist eine reine Beispielimplementierung. Folgende Request-/Response-Beispiele werden vom/an die Backend-Server-Referenzimplementierung des Geschäftspartners übermittelt: Beispiel-Request: Http-Method: POST Content-Type: application/x-www-form-urlencoded Headers: {connection=[keep-alive], Content-Length=[75], content-type=[application/x-www-formurlencoded], host=[my.merchantserver.biz:8080], user-agent=[android - PSC (v0.1 Prototype)]} Payload: transactionid=f24f06f5-0c4a-497e-aa66-90c3b34a07bf &amount=1.00¤cy=eur Beispiel-Response: Response-Code: 200 Content-Type: application/json Headers: {Date=[Wed, 27 Jul 2011 16:44:23 GMT]} Payload: { initiatepaymentresponse :{ paymentpanelurl : https%3a%2f%2fcustomer.test.at.paysafecard. com%2fpsccustomer%2fgetcustomerpanelservlet%3fmid%3d1000003265%26mtid%3d f24f06f5-0c4a- 497e-aa66-90c3b34a07bf %26amount%3D1%2C00%26currency%3DEUR }} Der Backend-Server gibt ein schlankes JSON-Objekt mit einer codierten Zahlungsfenster-URL zurück. Im nächsten Schritt wird diese URL in einem externen Browserfenster geöffnet. Weitere Details zur Implementierung des Backend Servers entnehmen Sie bitte unserer Referenzimplementierung. 11.3.2 Kommunikation zwischen Mobile App und Schließen des Client-Browsers Diese Beispiel beschreibt den Umgang mit okurl und nokurl auf dem Mobilgerät. okurl und nokurl werden auf dem Backend Server und in einer ANDROID App spezifiziert. Der Backend Server übermittelt okurl und nokurl an die App. Nach erfolgreicher Zuweisung der paysafecard PIN sendet die Zahlungsapp (vom Benutzerstandpunkt im Webbrowser) einen Intent mit der angegebenen okurl und nokurl. HINWEIS: Das angelegte Ereignis erfordert eine Reaktion. Dazu haben wir in AndroidManifest.xml folgende Konfiguration für PaySafeCardActivityWithBrowser angegeben: <activity android:name=.payment.paysafecardactivitywithbrowser android:theme= @android:style/theme.translucent.notitlebar android:screenorientation= portrait > <intent-filter> <data android:scheme= paysafecard /> <action android:name= android.intent.action.view /> <category android:name= android.intent.category.default /> <category android:name= android.intent.category.browsable /> </intent-filter> </activity> 22
Immer wenn eine Weiterleitung zu okurl und nokurl mit dem Schema paysafecard in einer ANDROID- Umgebung aufgerufen wird, wird die Activity PaySafeCardActivityWithBrowser gestartet. In diesem Fall wird die Aktion handlebrowsercallbackaction aufgerufen: private void handlebrowsercallbackaction(final Intent intent) { String uri = intent.getdatastring(); if (uri.contains(payment_ok)) { finishactivitywithsuccess(); } else { finishactivitywithfail(); } } Durch diese Vorgehensweise kann geprüft werden, ob createdisposition und die paysafecard Zuweisung erfolgreich waren. Eine Prüfung, ob der Backend Server mit der okurl oder nokurl antwortet, ist erforderlich. Im Erfolgsfall kann die Zahlung durchgeführt und die paysafecard des Anwenders mit dem Betrag belastet werden: private void finishactivitywithsuccess() { fulfillpaymenttask = new FulfillPaymentTask(ConnectorFactory.instance().get()); fulfillpaymenttask.bindcontext(paysafecardactivitywithwebview.this); fulfillpaymenttask.registerlistener(new FulfillPaymentResultListener()); fulfillpaymenttask.execute(pscbean); } Das kann auch in AsyncTask geschehen, um eine Sperrung der Benutzeroberfläche im Haupt-Thread zu verhindern. Diese Task könnte auch als Antwort auf eine Callback Methode eingesetzt werden, um Informationen bereitzustellen, wenn die Aktion executedebit erfolgreich durchgeführt wurde. Anschließend sollte die Activity PaySafeCardActivityWithBrowser dem Endanwender einige Informationen anzeigen. 23