Merchant Refund SOPG ( xml-basiertes Protokoll) Dokumentation Versionshistorie Version Datum Beschreibung Verfasser 1,0 05.11.2013 Erste veröffentlichungsreife Version Yuri Petersen 1,1 13.11.2013 Unnötige Parameter aus SOPG Call entfernt. Yuri Petersen 1,2 23.06.2014 Rückerstattung klassischer Zahlungen aufgenommen Yuri Petersen 1,3 17.11.2014 Kleinere Änderungen Techsupport Mit technischen Fragen zur Implementierung wenden Sie sich bitte an integration@paysafecard.com 1
Inhaltsverzeichnis 1. Einführung 3 2. Zahlung, SOPG und paysafecard Systeme 3 3. Übersicht Rückerstattungsprozess 4 3.1 Voraussetzungen 4 3.2 Zahlung 4 3.3 Vorprüfung Rückerstattung 4 3.4 Rückerstattung 5 3.5 Abrechnung 5 3.6 Zwei Zahlungsszenarien 5 3.7 Ablaufdiagramm Rückerstattung 5 4. Rückerstattung: Operationsdetails und WSDL-Vertrag 6 4.1 Meldungsstruktur Rückerstattung 6 4.2 Rückerstattungsparameter 6 4.3 Beispielrückerstattung 7 5. Anhang A: Fehlercodes 8 2
1. Einführung Dieses Dokument bietet einen detaillierten Überblick über Nutzung und Parameter des Prepaid Gateway (SOPG) von paysafecard für die Rückerstattung von Zahlungen durch Geschäftspartner. Dieses Dokument ergänzt die SOPG Zahlungsdokumentation, die Sie hier herunterladen können: https://www.paysafecard.com/fileadmin/website/dokumente/b2b/paysafecard_classic_payment_api_de.pdf Ein Implementierungsbeispiel finden Sie am Ende des Dokuments. 2. Zahlung, SOPG und paysafecard Systeme Information zu Definition Zu finden unter Klassische paysafecard Zahlung SOPG API (SOAP-basierter XML-Webservice) paysafecard Systeme Dieses Dokument erklärt den Ablauf einer klassischen paysafecard Zahlung und wird benötigt, um die Kernfunktionalität der paysafecard API zu verstehen. Dieses Kapitel erklärt die Definition der Clientfunktionalitäten der paysafecard API. Dieses Kapitel bietet einen Überblick über die paysafecard Umgebungen. Dokument: https://www.paysafecard.com/fileadmin/website/ Dokumente/B2B/paysafecard_classic_payment_api_de.pdf Dokument: https://www.paysafecard.com/fileadmin/website/ Dokumente/B2B/paysafecard_classic_payment_api_de.pdf Chapter: 3 Dokument: https://www.paysafecard.com/fileadmin/website/ Dokumente/B2B/paysafecard_classic_payment_api_de.pdf Chapter: 4 Umgang mit Fehlern Liste aller Fehlercodes. Dokument: https://www.paysafecard.com/fileadmin/website/ Dokumente/B2B/paysafecard_classic_payment_api_de.pdf Chapter: 8 3
3. Übersicht Rückerstattungsprozess Die Funktion Refund bietet Geschäftspartnern die Möglichkeit, zuvor erhaltene paysafecard Zahlungen (teilweise) an das my paysafecard Konto des Kunden zurückzuerstatten. 3.1 Voraussetzungen Der Geschäftspartner muss die SOPG-Funktionen für den Merchant Refund auf Website oder Backendsystem implementiert haben. Der Geschäftspartner muss voll integriert und Rückerstattungen müssen durch paysafecard freigeschaltet sein. Der Kunde muss über ein my paysafecard Konto verfügen, um Rückerstattungen erhalten zu können. 3.2 Zahlung Rückerstattungstransaktionen stehen immer in Bezug zu vorangegangenen Zahlungen. Folglich muss eine Zahlung erfolgt sein, bevor eine Rückerstattung vorgenommen werden kann. 3.3 Vorprüfung Rückerstattung Um sicherzustellen, dass die angeforderte Rückerstattung durchgeführt werden kann, muss der Geschäftspartner vorab prüfen ob eine Rückerstattung möglich ist. Unter bestimmten Bedingungen kann es zu einer Ablehnung der Rückerstattung kommen. Die Vorprüfung wird durch Übermitteln des Parameters validateonly = true im Rahmen eines Refund Requests durchgeführt. 4
3.4 Rückerstattung Sobald die Vorprüfung erfolgreich durchgeführt wurde, kann der Geschäftspartner die Rückerstattung an den paysafecard Kunden anfordern und bei Erfolg schreibt paysafecard den Rückerstattungsbetrag auf dem my paysafecard Konto des Kunden gut. 3.5 Abrechnung Alle erfolgreich durchgeführten Rückerstattungen werden von den Zahlungen (Saldierung) auf der monatlichen Rechnung abgezogen, die paysafecard an seine Geschäftspartner sendet. 3.6 Zwei Zahlungsszenarien paysafecard bietet zwei Zahlungsprodukte an: my paysafecard Zahlung Diese Zahlungen werden von Kunden über ihr my paysafecard Konto vorgenommen, die Kunden verfügen also über ein registriertes Konto bei paysafecard. Eine Rückerstattung dieser Transaktionen wird ebenso auf dieses Konto gemacht. Klassische Zahlung Bei einer klassischen Zahlung hat der Kunde eine paysafecard PIN erworben und mit dieser beim Geschäftspartner bezahlt. Diese Zahlung ist anonym und eine Rückerstattung muss dennoch auf ein my paysafecard Konto erfolgen. Im Rahmen des Rückerstattungsprozesses muss der Geschäftspartner die E-Mail Adresse des Kunden angeben, damit paysafecard weiß, an welchen Kunden die Rückerstattung überwiesen werden soll. Der Kunde muss also über ein registriertes Konto bei paysafecard verfügen, um die Rückerstattung erhalten zu können. 3.7 Ablaufdiagramm Rückerstattung 5
4. Rückerstattung: Funktionsdetails und WSDL-Struktur Dieses Kapitel beschreibt alle im Rahmen der Rückerstattung durchgeführten SOPG Funktionen. Alle erforderlichen Operationen für den Einzahlungsprozess sind in der klassischen SOPG-Dokumentation beschrieben. Alle erforderlichen Parameter müssen angegeben und übermittelt werden, auch wenn der Wert NULL bleibt. Benötigt das Webservice Framework eine WDSL zur Laufzeit, 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. 4.1 Meldungsstruktur Rückerstattung Name d. Funktion Beschreibung Request-Elemente Response- Elemente refund Aufladen des my paysafecard Kontos des Kunden mit dem jeweiligen Betrag in der jeweiligen Währung username [erforderlich] password [erforderlich] rtid [erforderlich] mtid [erforderlich] amount [erforderlich] currency [erforderlich] validateonly [erforderlich] utcoffset [erforderlich] customerldtype [optional] customerid [optional] rtid, mtid, currency, amount, validationonly, resultcode, errorcode, errorcode Beschreibung 4.2 Rückerstattungsparameter username Benutzername SOPG-Konto Authentifizierungsinformation, von paysafecard zur Verfügung gestellt. password Passwort SOPG-Konto Authentifizierungsinformation, von paysafecard zur Verfügung gestellt. rtid (eindeutige) ID der Rückerstattungstransaktion max. Länge: 90 Zeichen, Empfehlung: bis zu 20 Zeichen durch Geschäftspartner bereitgestellt zulässig sind nur: A-Z, a-z, 0-9 sowie - (Bindestrich) und _ (Unterstrich) Beispiel: 3516-6s4dfsad41 mtid (eindeutige) ID der (teilweise) zurückzuerstattenden Transaktion max. Länge: 90 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: 3516-6s4dfsad41 amount Rückerstattungsbetrag Der angefragte Betrag darf den Betrag der Ursprungstransaktion nicht überschreiten max. 11 Ziffern vor - exakt 2 Ziffern nach dem Dezimalpunkt Verwenden Sie einen Punkt als Dezimaltrennzeichen Beispiel: 100.00 6
currency Währung des Rückerstattungsbetrags max. Länge: 3 Zeichen, alles Großbuchstaben ISO-Währungscode Beispiel: EUR validationonly Bei Aktivierung dieses Parameters wird die Rückerstattung lediglich simuliert, um zu prüfen, ob sie erfolgreich durchgeführt werden könnte. Es erfolgt keine reale Übermittlung. Eine erfolgreiche Validierung ist keine 100 %ige Garantie dafür, dass die Durchführung der Rückerstattung erfolgreich sein wird. max. Länge: 1 Ziffer Beispiel: 1 oder 0. utcoffset - Differenz zur koordinierten Weltzeit (UTC) in Stunden und Minuten Beispiel: -03:00 customeridtype verwendete Authentifizierungsmethode für die Identifikation des my paysafecard Kontos möglicher Wert: EMAIL Parameter müssen bei Rückerstattung einer klassischen Zahlung angegeben werden customerid bezieht sich auf den customerldtype max. Länge: 90 Zeichen Parameter müssen bei Rückerstattung einer klassischen Zahlung angegeben werden Die E-Mail Adresse des my paysafecard Kontos. merchantclientid eindeutiger Identifikator für den Endkunden (die eindeutige ID, mit der der Endkunde in der Datenbank des Geschäftspartners registriert ist) HINWEIS: Verwenden Sie aus Sicherheitsgründen den registrierten Benutzernamen des Kunden nur verschlüsselt Parameter müssen bei Rückerstattung einer klassischen Zahlung angegeben werden max. Länge: 50 Zeichen Beispiel: client123 4.3 Beispielrückerstattung Beispiel-Request: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:urn= urn:pscservice > <soapenv:header/> <soapenv:body> <urn:refund> <urn:username>test</urn:username> <urn:password>test</urn:password> <urn:rtid>dv-ref-test8-refund</urn:rtid> <urn:mtid>dv-ref-test8</urn:mtid> <urn:amount>10.00</urn:amount> <urn:currency>eur</urn:currency> <urn:customeridtype>email</urn:customeridtype> <urn:customerid>customer@paysafecard.com</urn:customerid> <urn:merchantclientid>0uzl3mnyl</urn:merchantclientid <urn:validationonly>false</urn:validationonly> <urn:utcoffset >00:00</urn:utcOffset > </urn:refund> </soapenv:body> </soapenv:envelope> 7
Beispiel-Request: <soap:envelope xmlns:soap= http://schemas.xmlsoap.org/soap/envelope/ xmlns:ns1= urn:pscservice > <soap:body> <ns1:refundresponse> <ns1:refundrequestreturntype> <ns1:rtid>dv-ref-test8-refund</ns1:rtid> <ns1:mtid>dv-ref-test8</ns1:mtid> <ns1:amount>eur</ns1:amount> <ns1:currency>10.0</ns1:currency> <ns1:validationonly>false</ns1:validationonly> <ns1:resultcode>0</ns1:resultcode> <ns1:errorcode>0</ns1:errorcode> <ns1:errorcodedescription/> </ns1:refundrequestreturntype> </ns1:refundresponse> </soap:body> </soap:envelope> 5. Anhang A: Fehlercodes Sie finden alle Fehlercodes in der SOPG Zahlungsdokumentation. In diesem Kapitel sind lediglich rückzahlungsspezifische Fehlermeldungen aufgeführt. # Allgemeine Meldungen Fehler: 0001-0141 # Rückzahlungsspezifische Fehlermeldungen: 10007 ALLGEMEINER TECHNISCHER FEHLER 3100 PRODUKT NICHT VERFÜGBAR 3101 TERMINAL-LIMIT ÜBERSCHRITTEN 3102 AUFTRAG NICHT GEFUNDEN 3103 DOPPELTE AUFTRAGSANFRAGE 3104 PRODUKT NICHT VERFÜGBAR UNGLEICHE CACHE-ZUORDNUNG 3105 PRODUKT NICHT ZULÄSSIG 3106 FEHLER FORMAT KARTENWERT 3150 FEHLENDER PARAMETER 3151 UNGÜLTIGE WÄHRUNG 3152 FEHLENDER DISTRIBUTOR 3153 UNGÜLTIGER KARTENTYP 3154 ABBRECHEN AUFTRAG BEREITS VERARBEITET 3155 TERMINAL GESPERRT 3156 AUFTRAGSSTATUS ERLAUBT KEINEN ABBRUCH 3157 KUNDENIDENTIFIKATIONSTYP NICHT UNTERSTÜTZT 3158 ZU SPÄT FÜR AUFTRAGSABBRUCH 3159 MERCHANT FEHLT 3160 UNGÜLTIGER KUNDE 3161 MERCHANT NICHT FÜR PAYOUT FREIGEGEBEN 3162 KUNDE NICHT GEFUNDEN 3163 UNGÜLTIGER PARAMETER 3164 DOPPELTE AUSZAHLUNGSANFRAGE 3165 UNGÜLTIGER BETRAG 3166 MERCHANT-LIMIT ERREICHT 3167 KUNDEN-LIMIT ÜBERSCHRITTEN 3168 KYC FÜR AUSZAHLUNGSKUNDEN UNGÜLTIG 3169 PAYOUT-ID PASST NICHT ZU VORHANDENER DISPOSITIONS-ID 3170 AUFLADELIMIT ÜBERSCHRITTEN 3171 UNGÜLTIGER MINDESTAUSZAHLUNGSBETRAG 3172 AUSZAHLUNGSLIMIT DES KUNDEN ÜBERSCHRITTEN 3173 AUFTRAGSSTATUS UNTERSTÜTZT KEINE BESTÄTIGUNG 3179 RÜCKZAHLUNG GRÖSSER ALS URSPRUNGSTRANSAKTION 3180 UNGÜLTIGER STATUS DER URSPRUNGSTRANSKTION ZUR RÜCKZAHLUNG 3181 ABWEICHENDE CLIENT-IDS FÜR RÜCKZAHLUNG 3182 KEIN UNLOAD MERCHANT KONFIGURIERT 3184 RÜCKZAHLUNGSTRANSAKTION FEHLT 8