Du stehst auf eleganten Code und agile Softwareentwicklung? Wir auch! Bewirb dich, zeig uns was Du drauf hast und lerne unser Entwicklerteam kennen! Wir bieten dir die außergewöhnliche Mischung eines jungen Start-ups mit all seinen Vorteilen und die Professionalität eines seriösen Paymentanbieters.

» Junior Backend Engineer » Senior Backend Engineer » Systemadministrator

Zahlungs-Transaktionen

Erstellung von Zahlungs-Transaktionen

Die Kommunikation bei der Einlieferung von Transaktionen besteht aus nur einer Anfrage seitens des Online-Shops. Der schematische Ablauf sieht folgendermaßen aus:

Die URL https://api.barzahlen.de/v1/transactions/create wird mit einem POST-Request aufgerufen. Dabei werden verschiedene Variablen übertragen. Die Adressdaten des Kunden werden zur Ermittlung der nächstgelegenen Annahmestellen genutzt.

Im Erfolgsfall wird eine XML-Antwort zurückgegeben, die neben einer Referenz auf ein PDF-Dokument, welches den Zahlschein mit dem Barcode darstellt, auch eine Transaktions-ID enthält. Sie kennzeichnet die Transaktion eindeutig und muss gespeichert werden. Damit können z.B. Rückgaben über die API ausgelöst werden.

Weiterhin gibt es in der Antwort eine Anmerkung, die angibt, wie lange der Zahlschein vom Zeitpunkt der Erstellung an gültig ist und zwei Informationstexte, die HTML enthalten können. Die beiden Infotexte müssen untereinander angezeigt und entsprechend als HTML interpretiert werden.

Folgende XML-Antwort wird bei einer erfolgreichen Operation zurückgeliefert:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <transaction-id>227840174</transaction-id>
  <payment-slip-link>https://cdn.barzahlen.de/slip/227840174/c91dc292bdb8f0ba1a83c738119ef13e652a43b8a8f261cf93d3bfbf233d7da2/Zahlschein_Barzahlen_227840174.pdf</payment-slip-link>
  <expiration-notice>Der Zahlschein ist 2 Wochen gültig.</expiration-notice>
  <infotext-1>Text mit einem <a href="http://www.barzahlen.de" target="_blank">Link</a></infotext-1>
  <infotext-2>Text mit einem <a href="http://www.barzahlen.de" target="_blank">Link</a></infotext-2>
  <result>0</result>
  <hash>c5422fbcbaba04d65598cd847f2f91b1a18c6b0dc5eab927302affe235e6c37976307e23eef645b43b13c7d3cfbbbca9349247449a49b8aebcdd9b0a2554a893</hash>
</response>

Achtung: Der Link zum Zahlschein ist 14 Tage gültig. Danach führt der Aufruf zu einer Fehlermeldung. Der Kunde erhält jedoch von Barzahlen eine E-Mail mit dem Zahlschein in einer PDF-Datei als Anhang.

Insgesamt wird nur im Erfolgsfall der HTTP-Statuscode 200 zurückgeliefert. Zusätzlich gibt Result "0" an, dass der Vorgang erfolgreich war. Im Fehlerfall wird eine XML-Antwort zurückgegeben und der aufgetretene Fehler näher spezifiziert. Beispielsweise werden Transaktionen über 999,99 Euro abgelehnt.

Beschreibung der Parameter von /create

Legende

Formatangabe Erläuterung
N..X Numerischer Wert (maximal x Zeichen)
AN..X Alphanumerischer Wert (maximal x Zeichen)
Vorgabe Vorgabewerte (siehe Beschreibungsfeld)
Regulärer Ausdruck Ein regulärer Ausdruck definiert erlaubte Werte eindeutig.

Parameterbeschreibung

Die Übergabe der Daten erfolgt über einen HTTPS-POST Aufruf (key/value pairs). Die Antwort ist im XML-Format.

Parameter Beschreibung Format Pflicht
shop_id eindeutige Identifikationsnummer, um den Online-Shop zu identifizieren; im Händlerbereich von Barzahlen ersichtlich N..18 Ja
customer_email* E-Mail-Adresse des Kunden AN..80 Ja
amount positiver Betrag, nur Zahlen und ein "." erlaubt, < 1000.00 ˆ[0-9]{1,3}(\.[0-9][0-9]?)?$ Ja
currency 3-stelliger Währungscode (ISO 4217) Vorgabe Ja
order_id eindeutige Bestellnummer, damit die Transaktion vom Online-Shop zugeordnet werden kann AN..20 Nein
customer_street_nr Straße und Hausnummer des Kunden, zur Ermittlung der nächstgelegenen Annahmestellen (für Druck auf Zahlschein) AN..60 Ja
customer_zipcode Postleitzahl des Kunden, zur Ermittlung der nächstgelegenen Annahmestellen (für Druck auf Zahlschein) N..10 Ja
customer_city Wohnort des Kunden, zur Ermittlung der nächstgelegenen Annahmestellen (für Druck auf Zahlschein) AN..50 Ja
customer_country Land des Kunden (ISO 3166-1 alpha-2), zur Ermittlung der nächstgelegenen Annahmestellen (für Druck auf Zahlschein) Vorgabe Ja
language 2-stelliger Sprachcode (ISO 639-1), beeinflusst Sprache des Zahlscheins und der Antwort-Parameter, Standard ist DE Vorgabe Nein
custom_var_0 frei belegbare Variable (wird bei Benachrichtigung zurückgeschickt) AN..50 Nein
custom_var_1 frei belegbare Variable (wird bei Benachrichtigung zurückgeschickt) AN..50 Nein
custom_var_2 frei belegbare Variable (wird bei Benachrichtigung zurückgeschickt) AN..50 Nein
hash Hash aus Parametern und API- Zahlungsschlüssel des Online-Shops AN..128 Ja
due_date Tag bis zu welchem der Zahlschein gültig sein soll im Format ISO 8601 ("YYYY-MM-DD") Vorgabe Nein

* Unbedingtes Pflichtfeld (vgl. GwG); gültige E-Mail Formate sind die echte Kunden-E-Mail Adresse oder eindeutige Kundennummer@ihr-shop.de (hier muss eine Weiterleitung an den Kunden stattfinden)

Bildung des Hashwertes

Um die Integrität der übertragenen Daten zu überprüfen, wird ein Pre-Shared-Key-Verfahren eingesetzt. Der Online-Shop erhält dazu von Barzahlen einen Zahlungsschlüssel. Zusammen mit diesem Schlüssel wird mittels SHA-512 über alle übertragenen Daten ein Hash gebildet. Dieser Hashwert wird bei Barzahlen mit dem berechneten Hash aus eingegangenen Daten und dem Zahlungsschlüssel verglichen. So kann verifiziert werden, dass es sich um unveränderte Daten handelt.

Zur Generierung des Hashwertes muss zuerst eine Zeichenkette aus allen zu übermittelnden Daten gebildet werden. Dabei wird jeder Parameter durch das Semikolon ";" getrennt. Die Reihenfolge der Parameter spielt hierbei eine entscheidende Rolle.

Beim Einliefern von Transaktionen lautet die Reihenfolge:

  
shop_id;customer_email;amount;currency;language;order_id;
customer_street_nr;customer_zipcode;customer_city;customer_country;
custom_var_0;custom_var_1;custom_var_2;payment_key
  

Wichtig ist, dass auch nicht übergebene Parameter beachtet werden. Diese Parameter werden dann leer gelassen. Eine mögliche Zeichenkette sieht z. B. folgendermaßen aus:

  
94274;mail@domain.tld;21.99;EUR;DE;52847194;Dircksenstr;10178;Berlin;DE;
23;;;6a561c15e01eeec549e634ec69e737d7c37ca8fa
  

Der Hash muss im nächsten Schritt durch eine SHA-512 Funktion aus der vorangegangenen Zeichenkette berechnet und schließlich in hexadezimaler Form als Parameter "hash“ übertragen werden.

  
sha512(Zeichenkette);
  

Der resultierende Hash ist 128 Zeichen lang und sieht bei obiger Zeichenkette folgendermaßen aus:

  
eaf98825ac131df1375f7138a9fad189756a4addcf21efad0d70df5d83fbbe311cb095f6a4
e3175d9f4c767dd444163c7a07b33ce0293a9a2089e49100affcf1
  

Dynamische Fälligkeit

Der Parameter due_date erlaubt Ihnen die Fälligkeit jedes Zahlscheins einzeln festzulegen. Bitte beachten Sie, dass dieser Parameter von Barzahlen für Ihren Account erst aktiviert werden muss, bevor er genutzt werden kann.

Mindestens ein Werktag (Mo-Sa) muss zwischen dem Tag der Bestellung und dem due_date, welches im Format ISO 8601 ("YYYY-MM-DD") übertragen werden muss, liegen. Wird der Parameter nicht übertragen gilt die Standardgültigkeit, welche für den Online-Shop eingestellt wurde.

Bei der Übergabe eines ungültigen Wertes wird die Fehlermeldung "due_date not valid" mit Code 29 zurückgegeben.

Verifizierung der Antwort

Natürlich werden auch die Antworten von Barzahlen mit einem aus den zurückgelieferten Daten berechneten Hashwert ausgestattet. So kann die Integrität der Antwort vom Online-Shop überprüft werden. Die Reihenfolge der Parameter zur Berechnung des Hashwertes entspricht der in der XML-Antwort.

Beim Einliefern von Transaktionen lautet die Reihenfolge:

  
transaction-id;payment-slip-link;expiration-notice;infotext-1;infotext-2;
result;payment_key
  

Bei Übereinstimmung der berechneten Zeichenkette mit dem mitgelieferten Parameter "hash" kann die Antwort als verifiziert angesehen werden. Damit kann die Integrität der Antwort sichergestellt werden.