Hosted Payment Page
1.1 Allgemeines für Hosted Payment Page
1.3 Aufruf der Hosted Payment Page
2. 1cs Online Bezahlsystem-Schnittstelle
1. Über Hosted Payment Page
1.1 Allgemeines zur Hosted Payment Page
Die Hosted Payment Page ist ein Checkout, der nur den Schritt der Zahlarten-Auswahl enthält. Sie ist ein im responsiven Design gestaltetes HTML-Formular, welches auf allen Geräten korrekt dargestellt wird.
Bei Zahlungen über die Hosted Payment Page verbindet der Shop den Kunden mit dem HTML-Formular des 1cs Online Bezahlsystems, damit er dort die Zahlarten auswählt. Nach dem Bestätigen der Auswahl leitet das 1cs Online Bezahlsystem den Kunden, je nach Zahlart, entweder zu einem HTML-Formular des 1cs Online Bezahlsystems oder zu einem Formular des externen Dienstleisters und informiert den Shop nach Abschluss über das Zahlungsergebnis.
Folgende Tabelle enthält die Zahlarten, die Sie über die Hosted Payment Page nutzen können:
| Zahlungsart | PayType |
| Barzahlen | Barzahlen |
| Kreditkarte | CC |
| ClickToPay | ClickToPay |
| Lastschrift | EDD |
| PayPal | PayPal |
| Apple Pay | ApplePay |
| Google Pay | GooglePay |
| EasyCollect | EasyColl |
| EPS | EPS |
| iDEAL | iDEAL |
| Instanea | Instanea |
| Klarna | KlarnaPM |
| Boleto | BoletoPP |
| Chinapay | Chinapay |
| CUP | CUPPP |
| Sofort | Sofort |
| Alipay | Alipay |
| Bancontact | BanconPP |
| Bank Transfer | BankTranPP |
| Bluecode | Bluecode |
| Dragonpay | DragonPP |
| eNETS | ENETSPP |
| Finland Online Bank Transfer | FinOBTPP |
| Indonesia ATM | IndoATMPP |
| MB Way | MBWayPP |
| Multibanco | MultibanPP |
| My Bank | MyBankPP |
| MyClear FPX | MyClearPP |
| Pay by Bank | OpenBank |
| Przelewy 24 | P24PP |
| PostFinance | POSTFINPP |
| paysafecard | PSCPP |
| RHB Bank | RHB BankPP |
| SafetyPay | SafetyPPP |
| Swish | Swish |
| 7-Eleven | SevenElePP |
| Skrill | SkrillPP |
| TrustPay | TrustPayPP |
| Trustly | Trustly |
| TWINT | TWINT |
| WeCatPP | |
| VIPPS | VIPPS |
Folgende Tabelle enthält die Kartenmarken, die Sie über die Hosted Payment Page nutzen können. Bei Übergabe des Wertes CC im Parameter PayTypes werden alle für einen Händler konfigurierten Marken angezeigt. Die Auswahl bestimmter Marken ist durch die Übergabe einer Zeichenfolge der gewünschten Marken jeweils durch Pipe-Zeichen getrennt möglich.
| Kreditkartenmarke / Scheme Names → values for CCBrand |
| AirPlus |
| AMEX |
| ARGENCARD |
| Aura |
| Bancontact |
| CABAL |
| Cartes Bancaires |
| Maestro |
| CBN |
| CENCOSUD |
| ComfortCard |
| CUP |
| Dankort |
| DINERS |
| Discover |
| Elo |
| Hipercard |
| JCB |
| Maestro |
| MasterCard |
| NARANJA |
| RuPay |
| SHOPPING |
| TOTAL |
| VISA |
1.2 Ablauf der Zahlung
Um Zahlungen über die Hosted Payment Page auszuführen, rufen Sie folgende URL mit HTTPS GET oder HTTPS POST auf:
https://www.computop-paygate.com/paymentPage.aspx
Alle Daten, die für eine Zahlungsabwicklung notwendig sind, werden als Parameter übergeben. Damit weder der Kunde noch ein Dritter die Daten manipulieren kann, werden die Parameter mit Blowfish verschlüsselt.
Beim Aufruf des Formulars entschlüsselt das 1cs Online Bezahlsystem die Parameter und zeigt die HTML-Seite mit den Zahlungsarten an. Dort wählt der Kunde die Zahlungsart aus und startet die Weiterleitung per Mausklick auf die Schaltfläche „Weiter“.
Nach Durchführung der Zahlung leitet das 1cs Online Bezahlsystem den Kunden per HTTPS GET auf eine Shop-Seite zurück (URLSuccess, URLFailure) und übergibt dabei das Zahlungsergebnis als Blowfish-verschlüsselte Parameter. Zusätzlich übermittelt das 1cs Online Bezahlsystem das Ergebnis per HTTPS POST an die Notify-Seite des Shops (URLNotify). Der Shop nimmt das Zahlungsergebnis entgegen und entschlüsselt die Daten, um den Kunden über den Status zu informieren.
1.3 Aufruf der Hosted Payment Page
Der Aufruf der Hosted Payment Page beginnt mit der korrekten Zusammenstellung der Parameter, die aus einem Schlüssel und einem Wert bestehen und durch ein Gleichheitszeichen (=) getrennt sind:
MerchantID=Test
Alle Parameter werden in einer Zeichenkette aneinandergereiht und durch das Zeichen & getrennt:
Amount=100&Currency=EUR&TransID=12345
Hinweis: Da die Zeichen „=“ und „&“ als Trennzeichen verwendet werden, können diese Zeichen nicht als Wert übergeben werden. Alle Werte, die Sie ohne Blowfish-Verschlüsselung übergeben, müssen URL-encoded sein.
Eine korrekte Parameter-Zeichenkette für das 1cs Online Bezahlsystem enthält grundsätzlich drei Parameter: MerchantID, Len und Data. Die Parameter MerchantID und Len sind unverschlüsselt. Nur der Parameter Data wird Blowfish-verschlüsselt:
MerchantID=Test&Len=67&Data=0A67FE96a65d384350F50FF1
Der Parameter Data enthält die sensiblen Zahlungsdaten wie Betrag und Währung. Die verschlüsselten Bytes sind Hex-codiert und auf zwei Zeichen von links mit einer Null aufgefüllt. Die Verschlüsselung erfolgt über Blowfish ECB und steht Ihnen als Source-Code und Komponente zur Verfügung.
Für die Entschlüsselung ist der Parameter Len sehr wichtig, der die Länge der unverschlüsselten(!) Zeichenkette im Parameter Data enthält. Da bei der Verschlüsselung mit Blowfish die zu verschlüsselnde Datenmenge auf ein Vielfaches von 8 vergrößert wird, muss bei der Entschlüsselung die korrekte Länge der Zeichenkette bekannt sein. Andernfalls tauchen am Ende der Zeichenkette zufällige Zeichen auf.
Die Übergabe der Parameter erfolgt per HTTPS POST oder HTTPS GET. Die empfohlene Übertragungsmethode ist HTTPS POST, weil die Parameterzeichenkette bei GET an die URL angehängt wird, die je nach Browser auf 2048 Bytes begrenzt ist.
Hinweis: Bitte beachten Sie, dass die maximale Länge einer Zahlungsanfrage auf 5120 Zeichen begrenzt ist. Wenn Sie längere Zeichenketten benötigen, melden Sie sich bitte beim First Cash Solution Support.
Die folgenden Listings zeigen die Entwicklung eines Zahlungsaufrufs. Das erste Listing ist die unverschlüsselte Parameterzeichenkette:
MerchantID=Test&TransID=100000001&Amount=11&Currency=EUR&URLSuccess=https://www.shop.de/ok.html&URLFailure=https://www.shop.de/failed.html&URLNotify=https://www.shop.com/notify.cgi&OrderDesc=Mein Einkauf
Hinweis: Bitte beachten Sie, dass jedem Parameter ein Wert zugewiesen wird. Leere Parameter dürfen nicht übergeben werden, da andernfalls die Zahlung scheitern kann.
Diese Zeichenkette wird verschlüsselt und als Parameter Data übergeben, so dass der HTTPS GET Aufruf der Hosted Payment Page so aussieht:
Hinweis: Bitte beachten Sie, dass Parameter wie Language oder URLBack unverschlüsselt übergeben werden. Eine Tabelle mit allen möglichen unverschlüsselten Parametern finden Sie ebenfalls in diesem Dokument.
2. Parameter für die Hosted Payment Page
2.1 Definitionen
2.1.1 Datenformate
| Format | Beschreibung |
| a | alphabetisch |
| as | alphabetisch mit Sonderzeichen |
| n | numerisch |
| an | alphanumerisch |
| ans | alphanumerisch mit Sonderzeichen |
| ns | numerisch mit Sonderzeichen |
| bool | Bool’scher Ausdruck (true oder false) |
| 3 | feste Länge mit 3 Stellen/Zeichen |
| ..3 | variable Länge mit maximal 3 Stellen/Zeichen |
| enum | Aufzählung erlaubter Werte |
| dttm | ISODateTime (JJJJ-MM-TTThh:mm:ss) |
2.1.2 Abkürzungen
| Abkürzung | Beschreibung | Kommentar |
| CND | Bedingung (condition) | |
| M | Pflicht (mandatory) | Wenn ein Parameter Pflicht ist, dann muss er vorhanden sein |
| O | optional | Wenn ein Parameter optional ist, dann kann er vorhanden sein, ist aber nicht erforderlich |
| C | bedingt (conditional) | Wenn ein Parameter bedingt ist, dann gibt es eine Bedingungsregel, die angibt, ob er Pflicht oder optional ist |
Hinweis: Bitte beachten Sie, dass die Bezeichnungen der Parameter in Groß- oder Kleinbuchstaben zurückgegeben werden können.
2.2 Parameter der Hosted Payment Page
Diese Parameter sind für alle Zahlungsarten Pflicht und müssen Blowfisch-verschlüsselt im Parameter Data an die Hosted Payment Page gesendet werden.
Hinweis: Alle weiteren, zahlungsartspezifischen Parameter entnehmen Sie bitte dem Handbuch der jeweiligen Zahlungsart.
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der 1cs vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den Helpdesk, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: A1 Währungstabelle |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| TransID | ans..64 | M | TransaktionsID, die für jede Zahlung eindeutig sein muss |
| RefNr | ns..30 | O | Eindeutige Referenznummer. Das genaue Format hängt von den Zahlarten Ihrer MerchantId ab. Wählen Sie das Format so, dass alle möglichen Zahlarten kompatibel sind. |
| OrderDesc | ans..384 | M | Beschreibung der gekauften Waren, Einzelpreise etc. Bitte beachten Sie: Die ersten 27 Zeichen erscheinen auf dem Kontoauszug des Kunden. Im Händler Cockpit können Sie die kompletten Daten einsehen. |
| UserData | ans..1024 | O | Wenn beim Aufruf angegeben, übergibt das OBS die Parameter mit dem Zahlungsergebnis an den Shop |
| URLSuccess | ans..256 | M | Vollständige URL, die das OBS aufruft, wenn die Zahlung erfolgreich war. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen nutzen Sie stattdessen den Parameter UserData. -> Allgemeine Hinweise: – Wir empfehlen, den Parameter „response=encrypted“ zu verwenden, um eine verschlüsselte Antwort von Paygate zu erhalten – Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess senden. Überprüfen Sie daher unbedingt den „code“-Wert des DATA-Elements. Nur eine Antwort mit „code=00000000“ sollte als erfolgreich angesehen werden. |
| URLFailure | ans..256 | M | Vollständige URL, die das OBS aufruft, wenn die Zahlung gescheitert ist. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen nutzen Sie stattdessen den Parameter UserData. -> Allgemeine Hinweise: – Wir empfehlen, den Parameter „response=encrypted“ zu verwenden, um eine verschlüsselte Antwort von Paygate zu erhalten – Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess/URLNotify senden. Überprüfen Sie daher unbedingt den „code“-Wert des DATA-Elements. Nur eine Antwort mit „code=00000000“ sollte als erfolgreich angesehen werden. |
| Response | a7 | O | Die Status-Rückmeldung, die das OBS an URLSuccess und URLFailure sendet, sollte verschlüsselt werden. Dazu übergeben Sie den Parameter Response=encrypt. |
| URLNotify | ans..256 | M | Vollständige URL, die das OBS aufruft, um den Shop zu benachrichtigen. Die URL darf nur über Port 443 aufgerufen werden. Sie darf keine Parameter enthalten: Nutzen Sie stattdessen den Parameter UserData. -> Allgemeine Hinweise: – Wir empfehlen, den Parameter „response=encrypted“ zu verwenden, um eine verschlüsselte Antwort von Paygate zu erhalten – Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess/URLNotify senden. Überprüfen Sie daher unbedingt den „code“-Wert des DATA-Elements. Nur eine Antwort mit „code=00000000“ sollte als erfolgreich angesehen werden. |
| ExpirationDate | ans..19 | O | Zeitstempel für den Endzeitpunkt des PaymentPage-Aufrufes, Angabe derzeit in europäischer Zeit (CET/DST). Zeitzonen-Auswertung wird demnächst einheitlich auf UTC geändert. Format: YYYY-MM-ddTHH:mm:ss |
Folgende Parameter sind optional und können unverschlüsselt an die Hosted Payment Page übergeben werden:
| Key | Format | CND | Beschreibung |
| Template | ans..20 | O | Name der XSLT-Datei mit Ihrem individuellen Layout für das HPP Bezahlformular. |
| CCTempplate | ans..20 | O | Name der XSLT-Datei mit Ihrem individuellen Layout für das Bezahlformular. Wenn Sie das neugestaltete und abwärtskompatible 1cs OBS-Template nutzen möchten, übergeben Sie den Templatenamen „ct_compatible“. Wenn Sie das responsive 1cs OBS-Template für mobile Endgeräte nutzen möchten, übergeben Sie den Templatenamen „ct_responsive“. Die Zahlungsart „Bancontact“ kann ebenfalls über die payssl.aspx aufgerufen werden. Dazu muss „template=ct_bcmc“ als Pflichtparameter übergeben werden, damit das spezielle Bancontact-Template aufgerufen werden kann. Dabei ist zu beachten, dass Bancontact als Zahlungsart im Checkout-Prozess bereits auswählbar sein muss. Das Template ist nicht modifizierbar und muss genauso verwendet werden, da es sich an strikten Bancontact-Richtlinien orientiert. Diese Variante gilt nur in Verbindung mit „Omnipay: EMS payment solutions“. |
| SDDTemplate | ans..20 | O | Name der XSLT-Datei mit Ihrem individuellen Layout für das Lastschriftenformular. Dies greift nur, wenn der Kunde Lastschrift als Zahlungsart auswählt und auf die Schaltfläche „Weiter“ klickt. Wenn Sie keinen Wert übergeben, wird das responsive 1cs-Lastschriftenformular-Template angezeigt. |
| ECTemplate | ans..20 | O | Name einer XSLT-Vorlage, um ein individuelles Layout für Ihr EasyCollect-Formular zu erstellen, das zu Ihrem Shop-Layout passt. Diese Vorlage wird nur verwendet, wenn der Kunde EasyCollect als Zahlungsmethode auswählt und auf „Weiter“ klickt. Wenn Sie keinen Wert eingeben, wird die Standardvorlage für EasyCollect-Formulare angezeigt. |
| Language | a2 (enum) | O | Sprachcode: <de> deutsch, <al> albanisch, <at> österreichisch, <cz/cs> tschechisch, <dk> dänisch, <en> englisch, <fi> finnisch, <fr> französisch, <gr> griechisch, <hu> ungarisch, <it> italienisch, <jp> japanisch, <nl> holländisch, <no> norwegisch, <pl> polnisch, <pt> portugiesisch, <ro> rumänisch, <ru> russisch, <es> spanisch, <se> schwedisch, <sk> slowakisch, <sl> slowenisch, <tr> türkisch, <zh> vereinfachtes chinesisch. Ohne Angabe ist die Sprache Deutsch. Die tatsächlich unterstützten Sprachen hängen vom verwendeten Template ab. |
| URLBack | ans..256 | O | Vollständige URL, die das Paygate aufruft, wenn der Kunde auf Abbruch klickt. Der Parameter „URLBack“ kann – sowohl unverschlüsselt ans 1cs OBS übermittelt werden (Kompabilitätsmodus) – als auch in den verschlüsselten Übergabeparametern (bevorzugte Variante). Wenn Sie Parameter/Werte in der URLBack übergeben möchten, so können Sie folgende Methode verwenden: URLBack=https://your.shop.com/back.php?param1%3Dvalue1%26param2%3Dvalue3%26status%3Dcancelled Wenn der Kunde auf Abbruch klickt, so wird die URL genauso aufgerufen, so dass Sie URL Decode verwenden können, um Parameter und Werte zu extrahieren. |
| PayTypes | ans..256 | O | Mit diesem Parameter können Sie die anzuzeigenden Zahlungsarten übersteuern, d.h. sie können in diesem Parameter Pipe-getrennt entscheiden, welche der zur Verfügung stehenden Zahlungsarten angezeigt werden. Die möglichen Werte entnehmen Sie aus der Spalte PayType in der obigen Tabelle der Zahlungsarten. Beispiel: …&PayTypes=CC|EDD|Alipay |
2.3 Allgemeine Antwortparamter der Hosted Payment Page
Diese Parameter sind für alle Zahlungsarten gleich. Mit dem Parameter pt können Sie sehen, welche Zahlungsmethode der Kunde verwendet hat. Bitte entnehmen Sie alle weiteren speziellen Parameter für eine Zahlungsart dem Handbuch der jeweiligen Zahlungsart.
Die folgende Tabelle beschreibt die Ergebnis-Parameter, die das Paygate an Ihre URLSuccess, URLFailure und URLNotify übergibt. Wenn Sie den Parameter Response=encrypt angegeben haben, werden die folgenden Parameter mit Blowfish verschlüsselt an Ihr System übergeben:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden.
die Parameter (z.B. mid, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der 1cs vergeben wird. |
| pt | ans..256 | O | Informationen über die verwendete Zahlungsart gemäß obiger Tabelle der Zahlungsarten |
| PayID | an33 | M | Vom 1cs OBS vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs OBS vergebene ID für alle einzelnen Transaktionen (Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..50 | O | OK oder AUTHORIZE_REQUEST (URLSuccess) sowie FAILED (URLFailure) |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description, sondern Code für die Auswertung des Transaktionsstatus! |
| Code | an8 | O | Fehlercode gemäß Paygate Antwort-Codes (A4 Fehlercodes) |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| UserData | ans..1024 | O | Wenn beim Aufruf angegeben, übergibt das 1cs OBS die Parameter mit dem Zahlungsergebnis an den Shop. |
| Plain | ans..50 | O | Ein einzelner Wert, der von Ihnen gesetzt werden kann, um Informationen wieder unverschlüsselt in der Antwort bzw. im Notify zurückzugeben, z.B. die MID. Da der „Plain“-Parameter Teil des verschlüsselten „Data“ im Computop Paygate ist, ist dieser vor Manipulationen geschützt. |
| Custom | ans..1024 | O | Der „Custom“-Parameter wird vor der Verschlüsselung an den Aufruf angehängt und ist Teil des verschlüsselten „Data“ im 1cs OBS Aufruf. Dadurch ist der Wert gegen Manipulation geschützt. Der Custom-Wert wird dann in Klartext an die 1cs OBS-Antwort angehängt und dabei wird „|“ durch „&“ ersetzt. Dadurch können Sie einen Custom-Wert übergeben und bekommen mehrere Key-Value-Paare zu Ihrer eigenen Verwendung in der Antwort zurück. |
