====== GiroCode API ======
Mit der GiroCode API ist es möglich, Zahldaten für einen EPC QR-Code oder eine giropay Zahlung zu hinterlegen und eine Referenznummer zu generieren.

===== Zahldaten hinterlegen =====

==== GiroCode (EPC) generieren ====
Die übergebenen Zahldaten werden für einen EPC QR-Code hinterlegt und eine GiroCode Referenznummer generiert.

=== 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 Projekts, welches GiroCode unterstützt |
|projectId      |Ja       |Integer     |Projekt-ID eines Projekts, welches GiroCode unterstützt |
|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 |
|paymentreference |Nein   |String(35)  |Zahlungsreferenz |
|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 |
|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**: EPC QR-Code in angegebener Auflösung als PNG \\ **epc-qr-optimizied**: Optimierter EPC 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 wurde. \\ 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 GiroCode 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 (giropay) generieren ====
Die übergebenen Zahldaten werden gespeichert und eine GiroCode Referenznummer reneriert.

=== Anfrage ===
**URL:** https://payment.girosolution.de/girocheckout/api/v2/girocode/createpayment \\
**Bereitzustellen von:** GiroCheckout \\
**Aufzurufen von:** Händler

== POST-Parameter ==
^Name           ^Pflicht  ^Type        ^Beschreibung   ^
|merchantId     |Ja       |Integer     |Händler-ID eines Projekts, welches GiroCode unterstützt |
|projectId      |Ja       |Integer     |Projekt-ID eines Projekts, welches GiroCode unterstützt |
|merchantTxId   |Ja       |String(255) |eindeutige Transaktions-ID des Händlers  |
|amount         |Ja       |Integer     |Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent |
|currency       |Ja       |String(3)   |Währung der Transaktion \\ EUR = Euro |
|purposetext    |Ja       |String(27)  |Verwendungszweck für die Zahlung |
|multiple       |Ja       |Integer     |Definiert, ob die Bezahlung mehrfach durchgeführt werden kann. \\ 0 = Einmalzahlung \\ 1 = Mehrfachzahlung |
|validtil       |Nein     |Integer     |Gültigkeitsdatum der Zahlung im Format YYYYMMDD |
|urlRedirect    |Nein     |String      |URL, an die der Kunde nach der Zahlung geschickt werden soll. |
|urlNotify      |Nein     |String      |URL, an die der Zahlungsausgang gemeldet werden soll. |
|format         |Ja       |String(20)  |Format der GiroCode Grafik in der Antwort. \\ **epc-qr**: EPC QR-Code in angegebener Auflösung als PNG \\ **epc-qr-optimizied**: Optimierter EPC QR-Code nahe der angegebenen Auflösung als PNG \\ **link-qr**: QR-Code mit Link zur giropay Zahlung \\ **none**: Keine Grafik |
|resolution |Nein |Integer     |Auflösung in Pixel (z.B. 250), wenn der GiroCode als Grafik angefordert wurde |
|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 GiroCode 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 |
|url            |Optional |String    |URL zur Zahlung (z.B. bei giropay Rechnung)|
^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 abrufen ====
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/get \\
**Bereitzustellen von:** GiroCheckout \\
**Aufzurufen von:** Händler

== POST-Parameter ==
^Name           ^Pflicht  ^Type        ^Beschreibung   ^
|merchantId     |Ja       |Integer     |Händler-ID eines Projekts, welches GiroCode unterstützt |
|projectId      |Ja       |Integer     |Projekt-ID eines Projekts, welches GiroCode unterstützt |
|girocodereference       |Ja       |String(10)  |eindeutige GiroCode Referenznummer  |
|format |Ja       |String(20)  |Format des GiroCode Grafik in der Antwort. \\ **epc-qr**: EPC QR-Code in angegebener Auflösung als PNG \\ **epc-qr-optimizied**: Optimierter EPC QR-Code nahe der angegebenen Auflösung als PNG \\ **link-qr**: QR-Code mit Link zur giropay Zahlung \\ **none**: Keine Grafik |
|resolution |Nein |Integer     |Auflösung in Pixel (z.B. 250), wenn der GiroCode als Grafik angefordert wurde |
|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, konnten die GiroCode Daten gelesen werden. Es wird als Antwort die GiroCode Referenznummer und der GiroCode 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 |
|url            |Optional |String    |URL zur Zahlung (z.B. bei giropay Rechnung)|
^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 nutzen =====

==== GiroCode EPC QR-Code ====