====== GiroCode ====== Mit GiroCode können Überweisungsdaten in einem QR Code dargestellt werden. Der GiroCode QR-Code kann von den App's der Sparkassen und Volks- und Raiffeisenbanken eingescannt werden. Die im QR-Code enthaltenen Zahldaten werden in eine Überweisungsvorlage der jeweiligen Banking App übernommen. Die Zahlung kann dort ausgeführt werden. Weitere Information zum GiroCode finden Sie unter [[https://www.girocode.de|www.girocode.de]]. Der QR-Code enthält alle für eine Überweisung relevanten Daten: * Empfängerkonto * Betrag (optional) * Verwendungszweck * Textschlüssel (PurposeCode) Anwendungsbeispiele: * Spenden * Beitragsrechnung * Zahlschein * Rechnung //Eine Rückmeldung über den Ausgang der Überweisung ist nicht möglich. Der Zahlungsempfänger muss den Zahlungseingang auf seinem Empfänger Girokonto überwachen.// **Beispiel für einen EPC QR-Code:** \\ {{:girocode:girocode_epc_example.png?nolink&200|}} ===== Integration ===== Die Erstellung des GiroCode erfolgt über die GiroCode API. Zur Vereinfachung der Integration steht unser PHP SDK zur Verfügung. ===== API Funktionen ===== ==== GiroCode generieren ==== Die übergebenen Zahldaten werden unter einer GiroCode Referenznummer abgelegt und es kann ein QR Code generiert werden. === Anfrage === **URL:** https://payment.girosolution.de/girocheckout/api/v2/girocode/createepc \\ **Bereitzustellen von:** GiroCheckout \\ **Aufzurufen von:** Händler == POST-Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |merchantId |Ja |Integer |Händler-ID eines GiroCode Projekts | |projectId |Ja |Integer |Projekt-ID eines GiroCode Projekts | |amount |Nein |Integer |Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent \\ Maximal 99999999999 (999.999.999,99) | |currency |Nein |String(3) |Währung der Transaktion \\ EUR = Euro | |purposetext |Nein |String(140) |Verwendungszweck für die Zahlung, wenn keine Zahlungsreferenz angegeben ist \\ Zulässige Zeichen: [[girocheckout:girocode:start#sepa_zeichensatz|SEPA Zeichensatz]] | |paymentreference |Nein |String(35) |Zahlungsreferenz, wenn kein Verwendungszweck angegeben ist | |purposecode |Nein |String(4) |Textschlüssel für die SEPA Überweisung (SEPA Category Purpose Code) | |infotext |Nein |String(70) |Informationstext für den Zahlenden wird in der APP angezeigt. | |receivername |Nein |String(70) |Kontoinhaber des Empfängerkontos \\ Zulässige Zeichen: [[girocheckout:girocode:start#sepa_zeichensatz|SEPA Zeichensatz]] | |receiveriban |Nein |String(34) |IBAN des Empfängerkontos | |receiverbic |Nein |String(11) |BIC des Empfängerkontos | |format |Ja |String(20) |Format der GiroCode Grafik in der Antwort. \\ **epc-qr**: QR-Code in angegebener Auflösung als PNG \\ **epc-qr-optimizied**: Optimierter QR-Code nahe der angegebenen Auflösung als PNG \\ **none**: Keine Grafik | |resolution |Nein |Integer |Auflösung in Pixel (z.B. 250), wenn der GiroCode als Grafik angefordert wird. \\ Maximal 500 | |hash |Ja |String(32)|HMAC MD5 hash über alle Werte des Aufrufs (siehe [[girocheckout:general:start#hash_generieren|hash generieren]])| === Antwort === Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde der GiroCode erfolgreich erstellt. Es wird als Antwort eine GiroCode Referenznummer und der QR Code im entsprechenden Format zurückgeliefert. == Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |rc |Ja |Integer |[[girocheckout:errorcodes|Fehlernummer]] | |msg |Ja |String |zusätzliche Informationen im Fehlerfall | |girocodereference |Optional |String(10)|eindeutige GiroCode Referenznummer | |image |Optional |String |Base64 kodiertes PNG Bild, wenn über Parameter **format** angefordert | ^HEADER Parameter^^^^ |hash |Ja |String |HMAC MD5 hash über alle Werte der Rückmeldung. Siehe [[girocheckout:general:start#uebermittlung_von_daten_ueber_einen_schnittstellenaufruf_an_den_haendler|hash der Rückantwort]] | ==== GiroCode abfragen ==== Anhand der übergebenen GiroCode Referenznummer können die hinterlegten Daten abgerufen werden. Des weiteren kann der GiroCode in einem anzugebenden Format generiert und zurückgeliefert werden. === Anfrage === **URL:** https://payment.girosolution.de/girocheckout/api/v2/girocode/getepc \\ **Bereitzustellen von:** GiroCheckout \\ **Aufzurufen von:** Händler == POST-Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |merchantId |Ja |Integer |Händler-ID eines GiroCode Projekts | |projectId |Ja |Integer |Projekt-ID eines GiroCode Projekts | |girocodereference |Ja |String(10) |eindeutige GiroCode Referenznummer | |format |Ja |String(20) |Format des GiroCode Grafik in der Antwort. \\ **epc-qr**: QR-Code in angegebener Auflösung als PNG \\ **epc-qr-optimizied**: Optimierter QR-Code nahe der angegebenen Auflösung als PNG \\ **none**: Keine Grafik | |resolution |Nein |Integer |Auflösung in Pixel (z.B. 250), wenn der GiroCode als Grafik angefordert wird. \\ Maximal 500 | |hash |Ja |String(32)|HMAC MD5 hash über alle Werte des Aufrufs (siehe [[girocheckout:general:start#hash_generieren|hash generieren]])| === Antwort === Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, werden die Daten des GiroCode und der QR Code im entsprechenden Format zurückgeliefert. == Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |rc |Ja |Integer |[[girocheckout:errorcodes|Fehlernummer]] | |msg |Ja |String |zusätzliche Informationen im Fehlerfall | |amount |Optional |Integer |Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent \\ Maximal 99999999999 (999.999.999,99) | |currency |Optional |String(3) |Währung der Transaktion \\ EUR = Euro | |purposetext |Optional |String(140) |Verwendungszweck | |paymentreference |Optional |String(35) |Zahlungsreferenz | |purposecode |Optional |String(4) |Textschlüssel für die SEPA Überweisung (SEPA Category Purpose Code) | |infotext |Optional |String(70) |Informationstext für den Zahlenden wird in der APP angezeigt. | |receivername |Optional |String(70) |Kontoinhaber des Empfängerkontos | |receiveriban |Optional |String(34) |IBAN des Empfängerkontos | |receiverbic |Optional |String(11) |BIC des Empfängerkontos | |girocodereference |Optional |String(10)|eindeutige GiroCode Referenznummer | |image |Optional |String |Base64 kodiertes PNG Bild, wenn über Parameter **format** angefordert | ^HEADER Parameter^^^^ |hash |Ja |String |HMAC MD5 hash über alle Werte der Rückmeldung. Siehe [[girocheckout:general:start#uebermittlung_von_daten_ueber_einen_schnittstellenaufruf_an_den_haendler|hash der Rückantwort]] | ====== Zusatzinformationen ====== ===== SEPA Zeichensatz ===== Für SEPA Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens folgende Zeichen gültig: * abcdefghijklmnopqrstuvwxyz * ABCDEFGHIJKLMNOPQRSTUVWXYZ * 0123456789 * ':?,-(+.)/ * sowie das Leerzeichen (Space)