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:

<a href=https://www.computop-paygate.com/paymentPage.aspx?MerchantID=Test&Len=162&Data=E98D40FFFD622C5FE7414F73539A1852C2CE7C8B09D34DF217E27FA2E194B9
968DE9ABAE3B1F44B5485EFE3EF2597C7395BADBAD4340CDFD000DD57129EEFAA0
BE904A7E2339DCF9363DA6ACDBE5EF98E169FC3092B160252A037135421FD0CE
092C174A7D1D63517BD45099AC2B682F5E3CD2C942A6F0E741A833C0&Language=
enURLBack=https://www.shop.com/canceled>

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

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

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=….