1 Grundlagen des Batch-Managers
1.3 Manuelle Übertragung von Batch-Dateien
1.4 FTP-Übertragung von Batch-Dateien
2.1 Format einzureichender Batch-Dateien
Dieses Handbuch beschreibt den Batch-Manager des 1cs Online Bezahlsystem, mit dem Sie gesammelte Transaktionen als Batch-Datei einreichen können.
Der folgende Abschnitt Einführung bietet zunächst eine kurze Einführung zum Einsatzgebiet des Batch-Managers. Wie die Namen Ihrer Batch-Dateien lauten müssen, beschreibt der Abschnitt Name der Batch-Dateien. Den Austausch der Batch-Dateien mit dem 1cs Online Bezahlsystem erklären die Abschnitte Manuelle Übertragung von Batch-Dateien sowie FTP-Übertragung von Batch-Dateien.
Damit das 1cs Online Bezahlsystem Ihre Batch-Dateien verarbeiten kann, müssen diese Dateien korrekt aufgebaut sein. Wie die Transaktionsdaten in der Batch-Datei aussehen müssen, beschreibt das Kapitel Format der Batch-Dateien.
Der Batch-Manager erlaubt die Übertragung von Zahlungstransaktionen in Form von Dateien. Dabei sammeln Sie Transaktionsdaten wie Kreditkartennummer, Betrag und Währung in einer Batch-Datei, die Sie später an das 1cs Online Bezahlsystem übertragen. Das 1cs Online Bezahlsystem führt dann die Zahlungen aus und speichert den Transaktionsstatus in der Batch-Datei. Nach der Verarbeitung kann der Händler die Batch-Datei mit den Angaben zum Transaktionsstatus per Download wieder abrufen.
Der Name einer neuen Batch-Datei beginnt mit dem Buchstaben T, der die von Ihnen übertragene (englisch: transferred) Originaldatei kennzeichnet. Danach folgt das Datum der Einreichung in umgekehrter Reihenfolge: z.B. 20160112. Darauf folgen die von Com-putop vergebene MerchantID sowie ein dreistelliger Zähler, der grundsätzlich zunächst 001 lautet. Sofern Sie an einem Tag mehrere Dateien einreichen, setzen Sie den Zähler weiter auf 002, 003, 004 usw. Die Dateiendung muss .DAT lauten.
Hinweis: Bitte beachten Sie, dass die Abfolge der Komponenten davon abhängig ist, ob sie als Händler die Batch-Dateien manuell über Das Händler Cockpit übertragen oder automatisiert per FTP oder sFTP. Ein Beispiel für die FTP/sFTP-Übertragung finden Sie im Kapitel FTP-Übertragung von Batch-Dateien.
Der Name einer Batch-Datei setzt sich aus vier Komponenten zusammen:
Dateiname bei manueller Übertragung via Händler Cockpit:
<Phase><Datum><MerchantID><Zähler>.dat
Dateiname bei automatisierter FTP-Übertragung:
<Phase><Datum><Zähler><MerchantID>.dat
Hinweis: Bitte beachten Sie, dass die Dateinamen für Händler Cockpit und SFTP-Übertragung unterschiedlich aufgebaut sind.
Folgende Tabelle beschreibt die Komponenten der Batch-Datei:
| Komponente | Beschreibung |
| Phase | T=Transferring, P=Processed |
| Datum | Datum im Format JJJJMMTT (Jahr, Monat, Tag) |
| Zähler | Dreistellig, zählt täglich hoch von 001, 002 bis 999 |
| MerchantID | MerchantID |
Die Verarbeitung der Batch-Datei durchläuft mehrere Phasen, die im Dateinamen festgehalten werden: Die Originaldatei des Händlers beginnt mit dem Buchstaben T. Nach der Verarbeitung erhält die Batch-Datei den Anfangsbuchstaben P für verarbeitet (englisch: processed).
Wenn ein Händler mit der MerchantID TestHaendler am 12.01.2016 zwei Batch-Dateien über das Händler Cockpit einreicht, erhalten diese zwei Dateien folgende Dateinamen:
Hinweis: Kurz nachdem Sie die Batch-Datei übertragen haben, beginnt die Verarbeitung der eingereichten Transaktionen. Nach der Übertragung und während der Verarbeitung erhält die Datei den Anfangsbuchstaben W für Waiting. Wird die T-Batchdatei via FTP/sFTP zur Verarbeitung eingereicht, muss die Phase nach dem Upload vom Händlersystem in W umbenannt werden. Erst nach diesem Schritt beginnt die Verarbeitung.
Nachdem alle Zahlungstransaktionen ausgeführt wurden, kennzeichnet das 1cs Online Bezahlsystem die verarbeiteten Dateien, die nun die Angaben zum Transaktionsstatus enthalten, mit dem Anfangsbuchstaben P für englisch: processed, die Sie in der Batch-Ansicht von das Händler Cockpit per Download abrufen können:
Die Batch-Schnittstelle ist im Händler Cockpit integriert, welches Sie auch zur Verwaltung Ihrer Transaktionen nutzen. Um eine Batch-Datei zu übertragen, melden Sie sich zunächst mit dem Internet-Browser an Ihrem Konto des Händler Cockpits an. Beachten Sie, dass für die Arbeit mit Batch-Dateien das Batch-Handling für Sie aktiviert sein muss. Öffnen Sie den Menüpunkt Vorgänge anlegen im Händler Cockpit und klicken auf das Register Batch-Dateien. Von da aus können Sie eingereichte und verarbeitete Batch-Dateien mit der Such- und Filterfunktion finden und auflisten. Im Kombinationsfeld Vorgangsmerkmale wählen Sie den Status Datei zur Verarbeitung, um alle derzeit in Bearbeitung befindlichen Batch-Dateien aufzulisten. Eine Suche nach dem Vorgangsmerkmal Datei verarbeitet zeigt Ihnen hingegen die bereits komplett verarbeiteten Batch-Dateien jeweils mit dem Status der Zahlungen an. Durch Anklicken des Dateinamens können Sie die Batch-Dateien per Download auf Ihrem PC speichern.
Um eine neue Batch-Datei an das 1cs Online Bezahlsystem zu übertragen, klicken Sie auf die Schaltfläche Upload und wählen dann mit der Schaltfläche Durchsuchen die Datei auf der lokalen Festplatte Ihres Computers aus. Die Übertragung können Sie nun mit der Schaltfläche Upload starten.
Hinweis: Die Verarbeitung der übertragenen Batch-Datei beginnt kurze Zeit nach der Übertragung. Da alle Batch-Dateien seriell hintereinander verarbeitet werden, beginnt die Verarbeitung Ihrer übertragenen Batch-Datei erst, wenn vorher eingereichte Batch-Dateien abgearbeitet sind.
Nach der Übertragung und während der Verarbeitung erhält die Datei den Anfangs-buchstaben W für Waiting. Wenn alle Zahlungen in der Batch-Datei verarbeitet wurden, erhält die Batch-Datei den neuen Anfangsbuchstaben P. Diese verarbeiteten Dateien können Sie in der Batch-Ansicht des Händler Cockpits anklicken, um sie per Download auf Ihrem Computer zu speichern, mit Excel auszuwerten oder an die Buchhaltung weiterzuleiten.
Zusätzlich zur manuellen Batch-Übertragung (vgl. Manuelle Übertragung von Batch-Dateien) erlaubt das 1cs Online Bezahlsystem auch die automatisierte Übertragung per FTP (File Transfer Protocol). Um eine Batch-Datei per FTP/sFTP zu übertragen, ist folgender Ablauf erforderlich:
1. Speichern der Transaktionsdaten in einer formatierten Batch-Datei
2. Verschlüsselung der Batch-Datei
3. Übertragung der Batch-Datei
4. Änderung der Phase nach dem Upload (T ® W)
5. Abholen der Batch-Datei nach der Verarbeitung
6. Status der Transaktionen prüfen
Transaktionen in der Batch-Datei speichern
Die Transaktionsdaten in den Batch-Dateien müssen der in nachfolgenden Kapitel Format der Batch-Dateien beschriebenen Struktur entsprechen.
Verschlüsselung der Batch-Datei
Aus Sicherheitsgründen müssen Batch-Dateien vor der FTP/sFTP-Übertragung verschlüsselt werden. Um größtmögliche Sicherheit zu gewährleisten, verwendet das 1cs Online Bezahlsystem die asymmetrische Verschlüsselung mit PGP (Pretty Good Privacy). Eine Verschlüsselung mit GPG (GNU Privacy Guard) ist auch möglich. Die abgelegte Datei muss aber dennoch die Endung PGP aufweisen, ansonsten ist keine Verarbeitung möglich.
Wenn mehrere Batch-Dateien eingereicht werden sollen, zum Beispiel für einen Händler mit der MerchantID MerchantID am 12.01.2016, dann erhalten diese zwei Dateien folgende Dateinamen (vgl. Kap. Name der Batch-Dateien):
Die anerkannt hohe Sicherheit der PGP-Verschlüsselung basiert auf einem Verfahren mit zwei Schlüsseln, einem privaten und einem öffentlichen Schlüssel. Für die Verschlüsselung Ihrer Batch-Datei erhalten Sie von Der First Cash Solution einen öffentlichen Schlüssel. Die damit verschlüsselte Batch-Datei kann danach nur mit dem geheimen privaten Schlüssel von Der First Cash Solution entschlüsselt werden.
Darüber hinaus generieren Sie ebenfalls einen öffentlichen und einen privaten Schlüssel für Ihre Firma. Die verarbeitete Batch-Datei verschlüsselt das 1cs Online Bezahlsystem mit Ihrem öffentlichen Schlüssel. Die Datei kann dann nur mit Ihrem geheimen privaten Schlüssel gelesen werden.
Der Inhalt der Batch-Datei besteht aus einem Kopfteil (englisch: Header), mehreren Einträgen (englisch: Records) und einem Fußteil (englisch: footer). Jeder Eintrag in der Datei ist eine Zeile, die mit CRLF (Eingabetaste) abgeschlossen wird. Die Werte innerhalb einer Zeile werden durch Kommata getrennt. Das Format wird daher auch als CSV-Format (englisch: comma separated values) bezeichnet.
Die folgenden Abschnitte beschreiben das Format der Batch-Datei, die Sie an das 1cs Online Bezahlsystem übertragen sowie die Antwort-Datei, in der das 1cs Online Bezahlsystem die Ergebnisse der Zahlungen speichert.
Das Listing weiter unten zeigt, aus welchen Komponenten der Inhalt einer Batch-Datei zusammengesetzt ist.
Hinweis: Beachten Sie bitte, dass die Batch-Datei keine Leerzeilen enthalten darf, auch nicht am Anfang oder Ende der Datei. Die in Listings verwendeten Leerzeilen dienen nur der Übersichtlichkeit.
Hinweis: Beachten Sie bitte, dass Textparameter wie “Reason” oder “OrderDesc” keine Kommata enthalten dürfen.
Hinweis: Bei den Batch-Versionen 2.x gibt es die <MID> als weiteres Feld. Damit ist es möglich als MasterMID für SubMID Transaktionen einzureichen.
Header
Type,MerchantID,Date,Version
Record
Type,Action,<Amount>,<Currency>,<TransID>,<Data depends on Action>
Footer
Type,CountRecords,SumAmount
Das folgende Listing ist ein Beispiel einer Batch-Datei für die Buchung von drei Kreditkartentransaktionen im Wert von 1,00 und 2,00 EUR. Für die erste Zahlung übergibt das Händlersystem die Referenznummer 123456, für die zweite und dritte keine:
HEAD,MerchantID,20160112,1.2
CC,Sale,100,EUR,1567890,123456,MasterCard,5490011234567890,200506,Ihre Bestellung vom 4. Jan.
CC,Sale,100,EUR,1567891,,MasterCard,5490011234567890,200506,Ihre Bestellung vom 4. Jan. CC,Sale,200,EUR,10202280,,VISA,4907621234567890,200504,Ihre Bestellung vom 04. Jan. FOOT,3,400
Die Beschreibung der einzelnen Felder und Werte, die innerhalb der Batch-Datei für den Datensatz (Record) zu verwenden sind, finden Sie im jeweiligen Batch-Kapitel der betreffenden Zahlungsart.
Die allgemeinen Parameter für die Übergabe im Header und Footer erklärt folgende Tabelle:
| Parameter | Format | CND | Beschreibung |
| Type | a..11 | M | HEAD für Header, FOOT für Footer, und zum Beispiel CC für Kreditkarte. Das Feld muss nicht auf 11 Stellen aufgefüllt werden. |
| MerchantID | ans..30 | M | Von Der First Cash Solution vergebene ID des Händlers |
| Date | dttm8 | M | Datum der Datei-Erstellung im Format YYYYMMDD |
| Version | an6 | M | Die verwendete Batch-Version bestimmt, welche optionalen Parameter mit verwendet werden. Die jeweils möglichen Versionen unterscheiden sich je nach durchgeführter Aktion und je nach Zahlungsart. Sie finden die möglichen Versionen im Batch-Kapitel zu den einzelnen Zahlungsarten. |
| CountRecords | n..5 | M | Anzahl eingereichter Records ohne Header und ohne Footer |
| SumAmount | n..10 | M | Summe aller Beträge (Amounts) in kleinster Währungseinheit, z.B. Cent bei EUR gemäß Währungstabelle. Bitte wenden Sie sich an den Helpdesk, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
Während der Verarbeitung der Transaktionen speichert der Batch-Manager den Transaktionsstatus in der Batch-Datei. Zu diesem Zweck werden die Transaktionseinträge im Record-Bereich um die zwei Felder Status und Code ergänzt:
Record
CC,Capture,<Amount>,<Currency>,<TransID>,<RefNr>,<PayID>,<Status>,<Code>
Hinweis: Bei Nutzung der Autorisierungsverlängerung kann die Batch-Antwort-Datei mehr Zeilen enthalten, als Sie eingereicht haben, weil das 1cs Online Bezahlsystem gescheiterte Autorisierungsverlängerungen als Renewal oder AuthSplit mit dem Status FAILED meldet. Diese Fälle erfordern Kontaktaufnahme mit dem Kunden!
Hinweis: Die Rückgabe der optionalen Parameter in der Antwort-Datei erfolgt generell nur, wenn diese in der eingereichten Datei auch angegeben sind. Es werden generell keine Versandinformationen in die Antwort-Datei geschrieben. Falls Sie die Daten nochmals benötigen, lesen Sie diese bitte beim entsprechenden Notify aus.
Die jeweiligen Antwortparameter, die der Batch-Manager im Record-Bereich zu jeder Transaktion speichert, finden Sie im jeweiligen Batch-Kapitel der betreffenden Zahlungsart.
Ab der Version 3.0 unterstützt das 1cs Online Bezahlsystem detaillierte Fehlercodes. Diese Codes sind achtstellig und hexadezimal kodiert. Der Aufbau und die Bedeutung der Fehlercodes werden hier anhand des folgenden Beispiels beschrieben:
2 105 0014
Die erste Stelle beschreibt den Schweregrad des Fehlers. Alle Werte größer 0 kennzeichnen Warnungen oder Fehler.
Hinweis: Ein Fehlercode bedeutet nicht zwingend, dass ein technischer Fehler im 1cs Online Bezahlsystem oder im Händlersystem aufgetreten ist. Das 1cs Online Bezahlsystem liefert auch dann einen Fehlercode, wenn eine Transaktion gescheitert ist, weil die Bank eine Zahlung regulär ablehnt.
Die 2. bis 4. Stelle des Fehlercodes beschreibt die Fehlerkategorie. Zu den Fehlerkategorien gehören Verschlüsselungs- (001) und Formatfehler (010) sowie die Angabe der Zahlungsmethoden, angefangen bei Kreditkarten (100) über Lastschriften (110) bis zu Cash&Go (140).
Die 5. bis 8. Stelle des Fehlercodes gibt einen Hinweis auf die Fehlerdetails. Zu den Details zählen Hinweise auf Konfigurationsprobleme wie fehlende TerminalIDs (0047), Ausfälle im Bankrechenzentrum des Karteninhabers (121) aber auch normale Ablehnungen von Kreditkartenzahlungen aufgrund abgelaufener Karten (110) oder Declined-Meldungen (0100).
Hinweis: Fehlerfreie Transaktionen werden aus Kompatibilitätsgründen zur Version 2.1 nicht durch acht sondern durch eine Null 0 gekennzeichnet.
Eine komplette Auflistung der 1cs Online Bezahlsystem Fehlercodes finden Sie sowohl in der Excel-Datei Fehlercodes im jeweils aktuellen 1cs Online Bezahlsystem-Client, den Sie von unserer Homepage herunterladen können, als auch im Dokument Fehlercodes.
“Als eine der bekanntesten Opernhäuser der Welt steht die Semperoper Dresden für herausragende Kultur und Qualität.
Im Bereich der Zahlungs-abwicklung setzen wir deshalb auf die 1cs – für uns die perfekte Kombination aus persönlicher Betreuung und individuelle Beratung auf höchstem Niveau.”
Doris Schneider,
Leiterin Vertrieb und Service
“Wir setzen bei Fahrrad XXL auf den verlässlichen Service der First Cash Solution und fühlen uns hier bestens aufgehoben!”
Peter Hürter, Fahrrad XXL
“Die First Cash Solution ist stets zuverlässig und bietet einen
super Service durch ständige Bereitschaft uns zu helfen
sowie schnelle und kompetente Antworten auf all unsere Fragen.”
Thomas Quindt,
Projektleiter SOCCERBEAT GmbH
Gebühr der Kartenorganisationen:
Werden von den Kreditkartenorganisationen wie Visa oder Mastercard erhoben, sie werden auch Card Scheme Fees (CSF) genannt.
Bearbeitungsgebühr:
Wird von Deinem Zahlungsanbieter/Acquirer berechnet, in Deinem Fall von uns (1cs). Sie wird auch Acquirer Service Fee (ASF) genannt.
Interchange-Gebühr:
Wird von der kartenherausgebenden Bank bzw. Issuer in Rechnung gestellt. Sie wird auch Interchange Fee (ICF) genannt.
“Hier wird uns bei jedem Anliegen kompetent, unkompliziert und schnell geholfen! Daher können wir die First Cash Solution nur empfehlen.”
Sandra von Bargen, Hachez CHOCOVERSUM GmbH
„Die unkomplizierte schnelle Betreuung passt 100% zu uns und unserem Abrechnungssystem.“
Markus Tanger, Road House Paderborn