Bluecode
1.2 Wie verknüpfen Kunden Bluecode mit ihrem Bankkonto?
1.3 Gibt es Zahlungslimits beim Bezahlen mit Bluecode?
1.4 Wie funktioniert die Bluecode QR-Code-Zahlung?
3.3 Reversal, Client-to-Server
4 1cs Online-Bezahlsystem-Schnittstelle
4.2 Aufruf der Schnittstelle für eine Bluecode-Webseitenzahlung mit QR-Code (Verkauf)
4.3 Stornierung (falls ein Zahlungsprozess nicht erfolgreich abgeschlossen wurde)
1. Über Bluecode
Allgemeine Informationen über Bluecode
1.1 Was ist Bluecode?
Logo
| Info | Typ |
| Bluecode ist die erste gesamteuropäische mobile Zahlungslösung, die bargeldlose Zahlungen per Android-Smartphone, iPhone und Apple Watch auf einer einheitlichen technologischen Plattform mit Mehrwertdiensten verbindet. Gemäß der europäischen Datenschutzgesetze werden mit den beteiligten Banken oder Händlern niemals persönliche Daten ausgetauscht und somit auch beim Zahlungsvorgang nicht übertragen oder auf dem Mobiltelefon gespeichert. Das sehr sichere auf TAN basierende Zahlungssystem funktioniert mit allen Girokonten und ist unabhängig von der Übertragungstechnologie (Barcode, QR-Code, Bluetooth). | Zahlungen per Wallet |
Bluecode startete 2017 in Österreich. Seit 2018 profitieren auch Alipay-Nutzer von einer Kooperation zwischen Bluecode und Alipay. Die Expansion auf den deutschen Markt erfolgte im gleichen Jahr.
1.2 Wie verknüpfen Kunden Bluecode mit ihrem Bankkonto?
Bei Bluecode gibt es zwei Wege, wie App-Nutzer ihr Bankkonto verknüpfen können:
1. Bei den Partnerbanken können sie sich sofort und direkt in ihrer Bank-App oder bei Online-Banking registrieren. Diese Registrierung ist besonders schnell und bei allen Bluecode-Partnerbanken möglich.
2. Bei allen anderen Banken können sie sich mit einem SEPA-Lastschriftvorgang registrieren. Das Lastschriftmandat wird gespeichert und die Zahlung von SIX Payment Services Ltd verarbeitet. SIX ist ein von der Finanzmarktaufsicht testiertes Unternehmen und einer der größten Abwickler von Lastschriften in den deutschsprachigen Ländern.
1.3 Gibt es Zahlungslimits beim Bezahlen mit Bluecode?
Aus Sicherheitsgründen begrenzt Bluecode die Anzahl der Zahlungen auf vier pro Stunde und zehn Zahlungen pro Tag bei einem Transaktionslimit von 400€. Dieses ist abhängig vom Issuer (Bank des Endkunden) und kann ggf. abweichen.
1.4 Wie funktioniert die Bluecode QR-Code-Zahlung?
Die Bluecode QR-Code-Zahlung ist eine Variante der E-Commerce-Zahlung. Das Kassensystem (Shop des Händlers) erzeugt einen QR-Code mit den Zahlungsdaten, indem es die Bluecode-API über das Paygate aufruft. Dann scannt der Kunde den QR-Code mit seinem Mobilgerät, um die Zahlung abzuschließen.
Weitere Informatiomnen finden Sie auch auf der Webseite von Bluecode (https://bluecode.com/de-de/b2b/haendler/, https://bluecode.com/en/b2b/merchants/).
2. Anwendungsfälle
| Unterstützte Anwendungsfälle | Unterstützte Schnittstellen | |||||
| Anwendungsfall | Beschreibung | Einfacher Prozess | S-2-S | Batch | Analytics PayByLink | HPP |
| Autorisierung + Buchung | Händler wollen eine Zahlung autorisieren und bei Lieferung buchen | nicht unterstützt verwenden Sie stattdessen “Sale”, um eine Zahlung in einem Schritt zu autorisieren und zu buchen | ||||
| Verkauf (Sale) | Händler möchten per Bluecode Geld von einem Kunden erhalten | Shop des Händlers startet eine Bluecode-Zahlungsanfrage und empfängt die URL zum QR-Code Kunde scannt den QR-Code mit der Bluecode-App Kunde bestätigt die Zahlung in der Bluecode-App Shop des Händlers erhält eine Benachrichtigung über die erfolgreiche Zahlung |  | | ||
| Voll- oder Teilgutschrift | Händler möchten einen Geldbetrag an den Kunden zurückerstatten, nachdem eine Zahlung erfolgreich abgeschlossen ist | Händler startet eine Gutschriftsanfrage Computop erfasst die Bluecode-Details aus der betreffenden Zahlung und veranlasst die Bluecode-Gutschrift Shop des Händlers erhält eine Benachrichtigung über die erfolgreiche Gutschrift | | | ||
| Voll- oder Teilstorno | Händler wollen eine nicht abgeschlossene Zahlung stornieren | wird nur für Zahlungen unterstützt, die nicht abgeschlossen sind für abgeschlossene Zahlungen verwenden Sie stattdessen eine Gutschrift | | |||
3. Diagramme zum Prozessablauf
3.1 Sale, Client-to-Server
3.2 Sale, Server-to-Server
3.3 Reversal / Credit, Server-to-Server
4. 1cs Online-Bezahlsystem-Schnittstelle
4.1 Definitionen
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) |
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.
4.2 Aufruf der Schnittstelle für eine Bluecode-Webseitenzahlung mit QR-Code (Verkauf)
Für Bluecode-Zahlungen sind Stornierungen und Gutschriften möglich, wie in den nachstehenden Kapiteln beschrieben ist. Im Batch-Modus sind nur Gutschriften möglich. Für Transaktionen an der Verkaufsstelle verwenden Sie bitte die Verbindung für Bluecode QR-Code-Zahlung.
Um eine Bluecode QR-Code-Zahlung per Weiterleitung zu einem Bluecode-Formular abzuwickeln, verwenden Sie bitte folgende URL: https://www.computop-paygate.com/Bluecode.aspx
Um eine Bluecode QR-Code-Zahlung per Server-zu-Server-Verbindung abzuwickeln, verwenden Sie bitte folgende URL – Sie müssen die Bluecode-URL in einen QR-Code umwandeln: https://www.computop-paygate.com/BluecodeS2S.aspx
Hinweis: Aus Sicherheitsgründen lehnt das 1cs Online-Bezahlsystem alle Zahlungsanfragen mit Formatfehlern ab. Bitte übergeben Sie deshalb bei jedem Parameter den korrekten Datentyp.
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| RefNr | ans..30 | O | Eindeutige Referenznummer für jede Zahlung – falls vorhanden, kann dieser Wert auf dem Kontoauszug des Kunden gedruckt werden (je nach Bank des Kunden). 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, …). |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den First Cash Solution Helpdesk, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | A3 | M | Währung, drei Zeichen DIN / ISO 4217. Derzeit wird nur EUR unterstützt. Hier eine Übersicht: Währungstabelle |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| OrderDesc | ans..26 | O | Ein optionaler weiterer Bezeichner für diese Transaktion. Soll auf dem Kundenbeleg gedruckt werden und die Transaktion auf dem Zettel identifizieren. Das Format dieser ID ist frei wählbar und wird nicht geprüft. |
| ShopURL | an..128 | O | URL des Web-Shops, zum Beispiel: https://testmerchant.com |
| AccOwner | ans..50 | M | Name des Kontoinhabers |
| IBAN | an..34 | O | IBAN des Nutzers, die voreingestellt im Überweisungsfenster erscheint (nur für DE möglich) |
| BIC | an..11 | O | BIC des Nutzers, die voreingestellt im Überweisungsfenster erscheint |
| AddrCountryCode | a2 | M | Ländercode zweistellig gemäß ISO 3166. Derzeit DE, AT, BE, NL, ES, CH, PL, IT zulässig. |
| Language | a2 | O | Sprache: de – deutsch, en – Englisch, fr- Französisch, nl – Niederländisch, pl – Polnisch |
| URLSuccess | ans..256 | M | Vollständige URL, die das Paygate 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 Paygateaufruft, 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 Paygate 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 Paygate 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. |
| UserData | ans..1024 | O | Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop. |
| ReqId | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das First Cash Solution Paygate keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das First Cash Solution Paygate für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. Bitte beachten Sie, dass eine ReqID nur 12 Monate gültig ist, danach wird sie vom 1cs Online Bezahlsystem gelöscht. |
| Channel | a9 | O | Einer der Werte “ecommerce” oder “mcommerce” ecommerce = Browser (Standardwert) mcommerce = App-Switch |
| 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 First Cash Solution 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 First Cash Solution Paygate Aufruf. Dadurch ist der Wert gegen Manipulation geschützt. Der Custom-Wert wird dann in Klartext an die First Cash Solution Paygate-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. |
| TotalAmount | n..10 | O | Gesamtpreis des Kaufs vor Trinkgeld und Rabatt |
| Discount | n..10 | O | Auf den TotalAmount angebotener Rabatt – ist eine positive Ganzzahl und kann auch Null sein. |
| TransactionDate | ans20 | O | UTC-Zeit der Transaktion im Format “JJJJ-MM-TTThh:mm:ssZ” |
Parameter für Zahlungen mit Bluecode Webseitenzahlung
Die folgende Tabelle beschreibt die Ergebnis-Parameter, die das 1cs Online-Bezahlsystem an Ihre URLSuccess, URLFailure oder 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. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| mid | ans..30 | M | HändlerID, die von First Cash Solution vergeben wird |
| PayID | an32 | M | Vom Paygate vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom Paygate vergebene ID für alle einzelnen Transaktionen (Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..30 | M | Eindeutige Referenznummer für Ihre Buchhaltung – sie ist auch die eindeutige Referenz für Bluecode. Sie muss auf Rechnung/Beleg des Kunden gedruckt werden. |
| RefNr | ans..30 | O | Eindeutige Referenznummer. Falls vorhanden, muss sie auf Rechnung/Beleg des Kunden gedruckt werden. 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, …). |
| TransactionID | ans..64 | M | Eindeutige Transaktionsnummer von Bluecode (acquirer_tx_id): muss auf der Kundenrechnung gedruckt werden; der Kunde findet die acqurier_tx_id auch im Verlauf seiner Bluecode-App. |
| InvoiceText | ans..400 | O | Optionaler Text für Rechnung/Beleg des Kunden; falls vorhanden, muss er gedruckt werden. |
| Status | a..50 | M | OK oder AUTHORIZED (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 | n8 | M | Fehlercode gemäß Paygate Antwort-Codes (A4 Fehlercodes) |
| UserData | ans..1024 | O | Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop. |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| 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 First Cash Solution 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 First Cash Solution Paygate Aufruf. Dadurch ist der Wert gegen Manipulation geschützt. Der Custom-Wert wird dann in Klartext an die First Cash Solution Paygate-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. |
| CodeExt | an3..30 | O | Fehlercode von Bluecode |
| QRCodeUrl | ans..128 | C | Nur beim Aufruf von BluecodeS2S.aspx: falls der Aufruf erfolgreich war, wird eine QR-Code-URL zruückgegeben, die in einen QR-Code umgewandelt werden kann |
Ergebnis-Parameter für URLNotify, URLSuccess und URLFailure bei Bluecode Webseitenzahlung.
4.3 Stornierung (falls ein Zahlungsprozess nicht erfolgreich abgeschlossen wurde)
Stornierungen von Zahlungen mit Bluecode QR-Code-Zahlung sind über eine Server-zu-Server-Kommunikation möglich. Das Paygate erlaubt nur Stornierungen, die sich auf eine zuvor über das Paygate erfolgte Autorisierung beziehen. Bei der Stornierung einer Zahlung für die gesamte Zahlung storniert. Für erfolgreich abgeschlossene Zahlungsvorgänge ist keine Stornierung möglich. Um dem Kunden Geld zu erstatten, verwenden Sie eine “Gutschrift”. Um eine Stornierung für eine Bluecode QR-Code-Zahlung über eine Server-zu-Server-Verbindung auszuführen, verwenden Sie bitte folgende URL: https://www.computop-paygate.com/reverse.aspx
Hinweis: Aus Sicherheitsgründen lehnt das Paygate alle Zahlungsanfragen mit Formatfehlern ab. Bitte übergeben Sie deshalb bei jedem Parameter den korrekten Datentyp.
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| PayID | an32 | M | Vom Paygate vergebene ID für die zu stornierende Zahlung |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| RefNr | ans..30 | O | Eindeutige Referenznummer für Ihre Buchhaltung. Der Wert wird bei einer Stornierung nicht an Bluecode gesendet. 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, …). |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den First Cash Solution 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: Währungstabelle |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| UserData | ans..256 | O | Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop. |
| ReqId | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das First Cash Solution Paygate keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das First Cash Solution Paygate für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. Bitte beachten Sie, dass eine ReqID nur 12 Monate gültig ist, danach wird sie vom 1cs Online Bezahlsystem gelöscht. |
Parameter für Storno von Bluecode QR-Code-Zahlungen
Folgende Tabelle beschreibt die Ergebnis-Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| mid | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom Paygate vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom Paygate 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 |
| RefNr | ans..30 | O | Eindeutige Referenznummer für Ihre Buchhaltung. Der Wert wird bei der Gutschrift nicht an Bluecode gesendet. 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, …). |
| Status | a..50 | M | OK (URLSuccess) oder 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 | n8 | M | Fehlercode gemäß 1cs Online Bezahlsystem Antwort-Codes (Fehlercodes) |
| UserData | ans..256 | O | Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop. |
| CodeExt | ans..30 | O | Fehlercode von Bluecode |
Ergebnis-Parameter für Storno von Bluecode QR-Code-Zahlungen.
4.4 Gutschrift mit Referenz
Gutschriften für Zahlungen mit alle Bluecode-Zahlungsvarianten sind über eine Server-zu-Server-Kommunikation möglich. Das Paygate erlaubt nur Gutschriften, die sich auf eine zuvor über das Paygate erfolgte Buchung beziehen. Die Höhe der Gutschrift ist auf die Höhe der vorangegangenen Buchung beschränkt. Um eine Gutschrift (Credit) mit Referenztransaktion auszuführen, verwenden Sie bitte folgende URL: https://www.computop-paygate.com/credit.aspx
Hinweis: Aus Sicherheitsgründen lehnt das Paygate alle Zahlungsanfragen mit Formatfehlern ab. Bitte übergeben Sie deshalb bei jedem Parameter den korrekten Datentyp. Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| PayID | an32 | M | Vom Paygate vergebene ID für die gutzuschreibende Zahlung |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| RefNr | ans..30 | O | Eindeutige Referenznummer für Ihre Buchhaltung. Der Wert wird bei der Gutschrift nicht an Bluecode gesendet. 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, …). |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den First Cash Solution 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: Währungstabelle |
| OrderDesc2 | O | Optionaler Grund für die Gutschrift, z.B. “Garantie” | |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| UserData | ans..256 | O | Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop. |
| ReqId | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt die First Cash Solution Paygate keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass die First Cash Solution Paygate für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. Bitte beachten Sie, dass eine ReqID nur 12 Monate gültig ist, danach wird sie vom 1cs Online Bezahlsystem gelöscht. |
| Reason | ans..256 | O | Grund der Gutschrift |
Parameter für Gutschriften von Bluecode-Zahlungen
Folgende Tabelle beschreibt die Ergebnis-Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| mid | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom Paygate vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom Paygate 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 |
| RefNr | ans..30 | O | Eindeutige Referenznummer für Ihre Buchhaltung. Der Wert wird bei der Gutschrift nicht an Bluecode gesendet. 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, …). |
| TransactionID | ans..64 | M | Eindeutige Transaktionsnummer von Bluecode (acquirer_tx_id): sie wird auf der Kundenrechnung gedruckt |
| Status | a..50 | M | OK (URLSuccess) oder 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 | n8 | M | Fehlercode gemäß 1cs Online Bezahlsystem Antwort-Codes (Fehlercodes) |
| UserData | ans..256 | O | Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop. |
| CodeExt | ans..30 | O | Fehlercode von Bluecode |
Ergebnis-Parameter für Gutschriften von Bluecode-Zahlungen.
5. Batch-Nutzung der Schnittstelle
5.1 Gutschrift mit Referenz
Grundsätzliche Informationen zur Arbeit mit Batch-Dateien sowie zu deren Aufbau erfahren Sie im separaten Handbuch zum Batchmanager. Im Batch-Verfahren sind nicht alle Funktionen verfügbar, die für die Online-Schnittstelle verfügbar sind.
Dieses Kapitel beschreibt die Parameter, die Sie im Datensatz (Record) für die Ausführung einer Kreditkartenzahlung übergeben müssen und welche Informationen Sie der Antwort-Datei über den Status des Zahlungsvorgangs entnehmen können.
Bei den Batch-Aufrufen ist die verwendete Batch-Version zu unterscheiden, wovon die optionalen Parameter abhängen. Alle mit „2.“ beginnen Versionsbezeichnungen betreffen Aufrufe für einen Konzern. Das bedeutet, innerhalb einer Batch-Datei mit einer bestimmten MerchantID können auch Transaktionen anderer Händler mit einer abweichenden Sub-MID übertragen werden.
Folgende Tabelle gibt eine Übersicht der pro Aktion jeweils möglichen Batch-Versionen und ihrer Besonderheiten:
| Action | Version | Beschreibung |
| Credit | 1.0 / 2.0 | Standardversion ohne Rückgabe von Parameter Code |
| 1.x / 2.x | mit RefNr (gilt für alle Versionen außer 1.0) |
Beschreibung der möglichen Batch-Versionen
Der Aufbau für eine Bluecode-Gutschrift in einer einzureichenden Batch-Datei sieht folgendermaßen aus:
HEAD,<MerchantID>,<Date>,<Version>
Bluecode,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>
FOOT,<CountRecords>,<SumAmount>
Beispiel für Master-MID-Funktion:
HEAD,[Master]MerchantID,Date,2.x
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
FOOT,CountRecords,SumAmount
Die folgende Tabelle beschreibt die einzelnen Felder und Werte, die im Datensatz (Record) innerhalb der Batch-Datei verwendet werden:
| Key | Format | CND | Beschreibung |
| Type | a..11 | M | HEAD für Header, FOOT für Footer, Bluecode für Bluecode |
| Action | a..20 | M | Der Action-Parameter definiert die Art der Transaktion: Credit (Gutschrift) |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den First Cash Solution 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: Währungstabelle |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| RefNr | ans..30 | O | Eindeutige Referenznummer für Ihre Buchhaltung. Der Wert wird bei der Gutschrift nicht an Bluecode gesendet. 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, …). |
| PayID | an32 | M | Vom Paygate vergebene ID für diese Transaktion |
Beschreibung der Felder im Datensatz von Batch-Dateien
Der Record-Bereich in der Antwort-Datei zu Batch-Transaktionen sieht folgendermaßen aus:
HEAD,<MerchantID>,<Date>,<Version>
Bluecode,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>
FOOT,<CountRecords>,<SumAmount>
Die folgende Tabelle beschreibt die Antwort-Parameter, die der Batch-Manager im Record-Bereich zu jeder Transaktion speichert (hier nicht erklärte Standardparameter wie etwa <TransID> oder <RefNR> und Aufrufparameter, werden unverändert zum Aufruf wieder zurückgegeben und sind vorstehend beschrieben):
| Key | Format | CND | Beschreibung |
| Action | a..20 | M | Der Action-Parameter definiert die Art der Transaktion: Credit (Gutschrift) |
| PayID | an32 | M | Vom Paygate vergebene ID für diese Transaktion |
| Status | a..50 | M | OK (URLSuccess) oder FAILED (URLFailure) |
| Code | n8 | M | Fehlercode gemäß Paygate Antwort-Codes (Fehlercodes) |
Beschreibung der Ergebnis-Parameter im Datensatz von Batch-Dateien.
6 Testdaten
Bluecode bietet zum Test der Funktionalität eine spezielle Sandbox-App ab. Diese Sandbox-App gibt es nicht in den offiziellen Appstores, aber hier:
| Smartphone | Link und Anmerkungen | QR-Code für einfachen Download der Bluecode Sandbox-App |
| iOS | https://install.appcenter.ms/orgs/bluecode-organization/apps/at.secure-shopping.bluecode.sandbox-ios/distribution_groups/public Hinweis zu iOS: Bei der ersten Installation der Sandbox-App muss der Firmen-App “bluesource” einmalig auf iOS-Geräten unter “Einstellungen> Allgemein> Profile & Gerätemanagement” vertraut werden. Erst danach kann die Sandbox-App auf iOS verwendet werden. |  |
| Android | https://install.appcenter.ms/orgs/bluecode-organization/apps/com.spt.bluecode.sandbox-android/distribution_groups/public |  |
Beachten Sie bitte:
Nach der Installation der Bluecode Sandbox-App muss der Bluecode mit einem Bankkonto verknüpft werden:
- Nach der Installation der Bluecode Sandbox-App müssen Sie eine PIN für die App einrichten
- Klicken Sie dann auf “Bankkonto verknüpfen” und geben bei der Banksuche “test” ein.
- Der Eintrag “Einen Testnutzer aktivieren” wird angezeigt. Durch Anklicken kann ein Testkonto hinzugefügt werden.
- Dafür wählen Sie den ersten Eintrag “Hypo Tirol”.
- Dann wird ein Bluecode für die Zahlung angezeigt.
- Zum Scannen eins QR-Codes mit Ihrem Smartphone tippen Sie auf das QR-Symbol links oben in der App, um die Kamera einzuschalten.
- Dann wird der Betrag zur Bestätigung auf dem Smartphone angezeigt. Sie bestätigen das durch “Wischen”.
In der Bluecode Sandbox-App werden keine “echten” Zahlungen ausgeführt, sie werden nur simuliert!
 | Die Bluecode Sandbox-App hat auch einige Transaktions-Limits (pro Stunde / pro Tag). Falls Sie die Transaktions-Limits deaktivieren müssen, senden Sie bitte eine E-Mail zusammen mit Ihrer Bluecode Sandbox-App “Bluecode ID” an devsupport@bluecode.com. Die Bluecode ID finden Sie hier: |
7 Wichtige Hinweise für den Wechsel zu Live-Zahlungen
Computop hat selbst eine zertifizierte Bluecode-Implementierung. Beim Umschalten vom Testbetrieb auf den Livebetrieb muss ein Händler jedoch sicherstellen, dass:
- er die Computop-URL “Bluecode.aspx” nutzt, um eine Bluecode-Zahlung mit einer Weiterleitung zur Bluecode-Seite mit dem QR-Code auszulösen
- er die Computop-URL “BluecodeS2S.aspx” nutzt, um eine Bluecode-URL zu erhalten, die vom Händlersystem in einen QR-Code umgewandelt werden muss
- Werte für den Aufrufparameter “RefNr” für jeden Zahlungsvorgang eindeutig sind – doppelte Werte werden abgelehnt
- Werte vom Antwortparameter “TransactionID” auf Rechnung / Beleg des Kunden gedruckt werden müssen
- Werte vom Antwortparameter “TransID” auf Rechnung / Beleg des Kunden gedruckt werden müssen, sofern sie nicht leer sind
