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 |
| Kreditkarte | CC |
| Lastschrift | EDD |
| PayPal | PayPal |
| iDEAL | iDEAL |
| Klarna | KlarnaPM |
| Sofort | Sofort |
| giropay | giropay |
| Alipay | Alipay |
| AstroPay | AstroPayPP |
| Bancontact | BanconPP |
| Bank Transfer | BankTranPP |
| BitPay | BitPayPP |
| Bluecode | Bluecode |
| Dragonpay | DragonPP |
| eNETS | ENETSPP |
| Finland Online Bank Transfer | FinOBTPP |
| Indonesia ATM | IndoATMPP |
| Multibanco | MultibanPP |
| My Bank | MyBankPP |
| MyClear FPX | MyClearPP |
| Przelewy 24 | P24PP |
| POLi | POLiPP |
| PostFinance | POSTFINPP |
| paysafecard | PSCPP |
| QIWI | QIWIPP |
| RHB Bank | RHB BankPP |
| SafetyPay | SafetyPPP |
| 7-Eleven | SevenElePP |
| Skrill | SkrillPP |
| TrustPay | TrustPayPP |
Die Anzeige bzw. Steuerung der CustomFields im Online Shop erfolgt im System über den Parameter CustomField, mehr dazu im Kapitel “Kreditkarte”.
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 |
| CENCOSUD |
| ComfortCard |
| CUP |
| Dankort |
| DINERS |
| Discover |
| Elo |
| Hipercard |
| JCB |
| Laser |
| 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 |
| 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. Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| 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 |
Parameter für Hosted Payment Page
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 Kreditkartenformular. Dies greift nur, wenn der Kunde eine Kreditkartenmarke auswählt und auf die Schaltfläche „Weiter“ klickt. Wenn Sie keinen Wert übergeben, wird das responsive 1cs-Kreditkartenformular-Template angezeigt. |
| 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. |
| Language | a2 (enum) | O | Sprachcode: <de> deutsch, <al> albanisch, <at> österreichisch, <cz/cs> tsche-chisch, <dk> dänisch, <en> englisch, <fi> finnisch, <fr> französisch, <gr> grie-chisch, <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ür-kisch, <zh> Simplified Chinese Ohne Angabe ist die Sprache Deutsch. -> Die tatsächlich unterstützten Sprachen hängen vom verwendeten Template ab. Hinweis: In den Ländern Albanien, Österreich, Japan, China und Russland wird das HPP Bezahlformular in englischer Sprache dargestellt. |
| 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 Paygate übermittelt werden (Kompabilitätsmodus) – als auch in den verschlüsselten Übergabeparametern (bevorzugte Variante) |
| 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 |
Optionale Parameter für Hosted Payment Page
3.0 1cs Online Bezahlsystem Anpassung der Standardvorlagen
Wie passe ich die Bezahlseite an?
Wenn sich der Händler dazu entscheidet, die standardmäßige 1cs Online Bezahlsystem-Bezahlseite zu verwenden, besteht die Möglichkeit, das Logo einzufügen und bis zu 9 spezifische Felder (auch CustomFields genannt) des Zahlungsformulars anzupassen.
| CustomField1 | ans..50 | O | Betrag und Währung der Transaction. | |
CustomField2 | ans..50 | O | Bestellnummer. | |
CustomField3 | ans..50 | O | Händlerlogo, URL des Logos. Format: .png Das Logo kann ich jeglicher Größe eingefügt werden, die Vorlagen passen die optimale Größe automatisch an. | |
CustomField4 | ans..50 | O | Bestellbeschreibung. | |
CustomField5 | ans..50 | O | Käufer Information. | |
CustomField6 | ans..50 | O | Versandinformation. | |
CustomField7 | ans..50 | O | Lieferung Informationen | |
| CustomField8 | ans..50 | O | Name eines neuen Feldes, das vom Händler hinzugefügt wurde | |
| CustomField9 | ans..50 | O | Wert eines neuen Feldes, das vom Händler hinzugefügt wurde | |
| URLBack | ans..50 | O | Auf diese Seite kommt der Kunde, wenn er sich dazu entscheidet die Zahlung zu stornieren. Verwenden Sie die Schaltfläche “x” in der oberen rechten Ecke. |
Zahlungsanforderung mit benutzerdefinierten Feldern:
…….aspx?MerchantID=Test&Len=67&Data=0A67FE96a65d384350F50FF1&CustomField1=…&CustomField2=….
