Classic Payment API - What is paysafecard?

Transcription

Classic Payment API
Service Oriented
Prepaid Gateway
Classic Payment API
SOPG (Service Oriented Prepaid Gateway – 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
umstrukturiert
Matthias Vilsecker
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 [email protected]
1
Classic Payment API
Service Oriented
Prepaid Gateway
Inhaltsverzeichnis
1.Einführung
2.Funktionsübersicht Zahlung
2.1 Ablauf von Zahlungen
2.2 my paysafecard
2.2.1KYC-Level
3.Über SOPG
3.1Voraussetzungen
3.2 Umgang mit Fehlern
3.2.1 Beschreibung Fehlermeldungen
3.3 Inhaltstyp und Zeichensatz
4.Definition von paysafecard Systemen
4.1 Testumgebung (M-Test)
5.Technische Übersicht
6.Funktionsdetails und WSDL-Struktur
6.1Funktionen
6.2Zahlungsbenachrichtigung
6.2.1 Neuübermittlung der Zahlungsbenachrichtigung
6.3Parameter
6.3.1 Beschreibung von Parametern
6.3.2Einschränkungen
6.3.3 Disposition Status
6.4Dispositionszeitfenster
6.5 Details Zahlungsfenster
6.5.1 Zahlungsfenster Desktop
6.5.2 Zahlungsfenster Mobilgeräte
6.6 Gebietsschema und Spracheinstellungen
7.Beispielzahlung
7.1createDisposition
7.2 getMid (optional)
7.3getCustomerPanel
7.4 pnUrl Request
7.4.1executeDebit
8.Anhang A: Fehlercodes
9.Anhang B: In Zahlungsbenachrichtigungen unterstützte Ländercodes
10. Anhang C: In App Payment
10.1 Zahlungsfenster-Details für In App Payments
10.2 Technische Übersicht
11. Beispielintegration In App Payment
11.1 Unterstützte Betriebssysteme
11.2 Technische Übersicht: Beispielintegration
11.3Implementierungsbeispiel
11.3.1 Initiieren der Zahlungskommunikation 11.3.2 Kommunikation zwischen Mobile App und Schließen des Client-Browsers
3
3
3
4
4
4
4
4
5
5
5
5
5
6
6
7
8
8
8
10
10
10
11
11
11
11
11
12
13
13
14
14
15
18
18
18
19
19
19
20
20
20
22
2
Classic Payment API
Service Oriented
Prepaid Gateway
1. Einführung
Dieses Dokument bietet einen detaillierten Überblick über Verwendung und Parameter des Service Oriented
Prepaid Gateway (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
Classic Payment API
Service Oriented
Prepaid Gateway
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 Service Oriented Prepaid Gateway (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
Classic Payment API
Service Oriented
Prepaid Gateway
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
Classic Payment API
Service Oriented
Prepaid Gateway
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.16.1 Funktionen
Name der
Funktion
Beschreibung
Request-Elemente
ResponseElemente
createDisposition
Der Geschäftspartner
initiiert den
Zahlungsprozess durch
Übermittlung eines
„createDisposition“
Requests an paysafecard,
durch das eine Disposition
auf dem Server angelegt
wird.
Der zulässige
Maximalbetrag liegt
bei 1.000,00 EUR (bzw.
einem gleichwertigen
Betrag in einer anderen
Transaktionswährung).
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]
mtid, subId,
mid, resultCode,
errorCode
Ermöglicht dem
Geschäftspartner, dem
Kunden die Zahlungsseite
für paysafecard Zahlungen
anzuzeigen.
Im Falle einer erfolgreichen
getCustomerPanel
paysafecard Zuweisung
wird der Kunde zur „okUrl“
weitergeleitet. Klickt der
Kunde auf „Abbrechen“,
wird er zur „nokUrl“
weitergeleitet.
executeDebit
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.
mid [erforderlich]
mtid [erforderlich]
language [optional]
locale [optional]
mtid [erforderlich]
close [erforderlich]
partialDebitId [optional]
mtid, subId,
resultCode,
errorCode
6
Classic Payment API
Service Oriented
Prepaid Gateway
Name der
Funktion
Beschreibung
Request-Elemente
ResponseElemente
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]
getSerialNumbers
(optional)
Ruft den Disposition
Status ab und prüft, ob
dieser dem erwarteten
Status entspricht, bevor
die nächste Funktion
aufgerufen wird.
mtid [erforderlich]
mtid, subId,
resultCode,
errorCode,
amount, currency,
dispositionState,
serialNumbers
modifyDisposition
Value (optional)
Möglichkeit, den Betrag der
mtid [erforderlich]
ursprünglichen Disposition
zu reduzieren.
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
Merchant
ResponseElemente
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
cardTypeld1
HTTP 200
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.
1
7
Classic Payment API
Service Oriented
Prepaid Gateway
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
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.
nokUrl – Die URL, zu der Kunden von paysafecard weitergeleitet werden, wenn Sie im paysafecard
Zahlungsfenster auf „Abbrechen“ klicken.
8
Classic Payment API
Service Oriented
Prepaid Gateway
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
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.
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
Classic Payment API
Service Oriented
Prepaid Gateway
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
COUNTRY
Beispielwert
mögliche Werte
Beschreibung
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
Classic Payment API
Service Oriented
Prepaid Gateway
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 Kunden1.
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
Classic Payment API
Service Oriented
Prepaid Gateway
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>

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

<urn:merchantclientid>cID_919191</urn:merchantclientid>

<urn:pnUrl> http%3a%2f%2fwww%2emerchantpnURL%2ecom </urn:pnUrl>
<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>

<urn:shopId>3516-6s4dfsad41</urn:shopId>

<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
Classic Payment API
Service Oriented
Prepaid Gateway
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:getMid>
</soapenv:Body>
</soapenv:Envelope>
Beispiel-Request:
<soapenv:Body>
<ns1:getMidResponse xmlns:ns1=“urn:pscservice“>
<ns1:getMidReturn>
<ns1:currency>EUR</ns1:currency>
<ns1:mid>1000001234</ns1:mid>
</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
&currency=EUR
Beispiel Eingabeparameter:
PIN: 0000 0000 1234 5678
Terms of Use: <checkbox, default unchecked>
13
Classic Payment API
Service Oriented
Prepaid Gateway
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:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</urn:mtid>
<urn:subId></urn:subId>
<urn:amount>10.00</urn:amount>
<urn:close>1</urn:close>
</urn:executeDebit>
</soapenv:Body>
</soapenv:Envelope>
Beispiel-Response:
<soapenv:Body>
<ns1:executeDebitResponse xmlns:ns1=“urn:pscservice“>
<ns1:executeDebitReturn>
<ns1:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</ns1:mtid>
<ns1:subId/>
</ns1:executeDebitReturn>
</ns1:executeDebitResponse>
</soapenv:Body>
</soapenv:Envelope>
14
Classic Payment API
Service Oriented
Prepaid Gateway
8. Anhang A: Fehlercodes
Können Sie einen Fehlercode nicht in der Liste finden, wenden Sie sich bitte an [email protected]
Beschreibung von resultcodes (Ergebniscodes):
Name Ergebnis
Beschreibung
resultCode
0 : erfolgreich
1 : logisches Problem
2 : technisches Problem
errorCode
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
Classic Payment API
Service Oriented
Prepaid Gateway
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
Classic Payment API
Service Oriented
Prepaid Gateway
# 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
Classic Payment API
Service Oriented
Prepaid Gateway
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-ISOLä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
Classic Payment API
Service Oriented
Prepaid Gateway
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
Classic Payment API
Service Oriented
Prepaid Gateway
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
Classic Payment API
Service Oriented
Prepaid Gateway
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
Classic Payment API
Service Oriented
Prepaid Gateway
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&currency=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-0c4a497e-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
Classic Payment API
Service Oriented
Prepaid Gateway
Immer wenn eine Weiterleitung zu „okUrl“ und „nokUrl“ mit dem Schema „paysafecard“ in einer ANDROIDUmgebung 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

Classic Payment API - What is paysafecard?

Transcription

Similar documents

classic payment api - What is paysafecard?

paysafecard: Online sicher bezahlen

Allgemeine Geschäftsbedingungen (AGB) für paysafecard