{{indexmenu_n>3}}
====== iDEAL API Funktionen ======

===== iDEAL Banken abrufen =====
Mit dieser Funktion können Sie eine Liste der iDEAL Issuer Banken abrufen. Diese Liste können Sie dem Kunde z.B. als Selectbox zur Auswahl anzeigen. So Sieht der Kunde direkt im Shop, ob seine Bank iDEAL unterstützt und er kann ohne Zwischenschritt zu seiner Bank weitergeleitet werden.

=== Anfrage ===
**URL:** https://payment.girosolution.de/girocheckout/api/v2/ideal/issuer \\
**Bereitzustellen von:** GiroSolution AG \\
**Aufzurufen von:** Händler

== Parameter ==
^Name           ^Pflicht  ^Type      ^Beschreibung   ^
|merchantId     |Ja       |Integer   |Händler-ID eines iDEAL Projekts |
|projectId      |Ja       |Integer   |Projekt-ID eines iDEAL Projekts |
|hash           |Ja       |String(32)|HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]]|

== Beispiel ==
{{page>codesamples:ideal#issuer.request&noheader&nofooter}}

=== Antwort ===
Die Antwort ist ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, enthält das Element **issuer** die zur Verfügung stehenden Banken. 
== Parameter ==
^Name           ^Pflicht  ^Type      ^Beschreibung   ^
|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] |
|msg            |Ja       |String    |Zusätzliche Informationen im Fehlerfall |
|issuer         |Optional |Array     |Liste der iDEAL issuer Banken |

== Beispiel im Erfolgsfall ==
{{page>codesamples:ideal#issuer.response.true&noheader&nofooter}}

== Beispiel im Fehlerfall ==
{{page>codesamples:ideal#issuer.response.false&noheader&nofooter}}

===== Initialisierung der iDEAL Zahlung =====

Sie übermitteln die Transaktionsdaten und erhalten einen Link (Redirect-URL) als Antwort. Anschließend senden Sie Ihrem Kunden eine Weiterleitung zur Redirect-URL. Dies kann durch einen HTTP-Redirect-Header, eine HTML-Seite mit entsprechendem Meta-Tag oder Javascript erfolgen. Die eigentliche Zahlungsabwicklung erfolgt dann, indem der Kunde sich beim Onlinebanking seiner Bank anmeldet und dort die vorausgefüllte Überweisung durchführt.
Die Benachrichtigung Ihrer Anwendung über den Ausgang der Zahlung erfolgt, indem Ihnen GiroCheckout einen GET-Request an die im Parameter urlNotify angegebene URL schickt.

=== Anfrage ===
**URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\
**Bereitzustellen von:** GiroSolution AG \\
**Aufzurufen von:** Händler

== Parameter ==
^Name           ^Pflicht  ^Type        ^Beschreibung   ^
|merchantId     |Ja       |Integer     |Händler-ID eines iDEAL Projekts |
|projectId      |Ja       |integer     |Projekt-ID eines iDEAL Projekts |
|merchantTxId   |Ja       |String(255) |Eindeutige Transaktions-ID des Händlers |
|amount         |Ja       |Integer     |Betrag in Cent\\ Wenn kind = 2, dann als Betrag 0 angeben |
|currency       |Optional |String(3)   |Währung der Transaktion\\ EUR = Euro (default) |
|purpose        |Ja       |String(27)  |Verwendungszweck der iDEAL Überweisung |
|issuer         |Ja       |String      |iDEAL Issuer Bank |
|urlRedirect    |Ja       |String      |URL, an die der Kunde nach Zahlung der Zahlung geschickt werden soll. |
|urlNotify      |Ja       |String      |URL, an die der Zahlungsausgang gemeldet werden soll. |
|hash           |Ja       |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |

== Beispiel ==
{{page>codesamples:ideal#transactionstart.request&noheader&nofooter}}

=== Antwort ===
Die Antwort ist ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, sind die Parameter reference und redirect gesetzt. Leiten Sie den Kunde bitte an die redirect URL weiter.
== Parameter ==
^Name           ^Pflicht  ^Type      ^Beschreibung   ^
|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] |
|msg            |Ja       |String    |Zusätzliche Informationen im Fehlerfall |
|reference      |Optional |String    |Eindeutige GiroCheckout Transaktions-ID |
|redirect       |Optional |String    |Redirect URL zur Weiterleitung des Kunden |

== Beispiel im Erfolgsfall ==
{{page>codesamples:ideal#transactionstart.response.true&noheader&nofooter}}

== Beispiel im Fehlerfall ==
{{page>codesamples:ideal#transactionstart.response.false&noheader&nofooter}}

===== Benachrichtigung über den Ausgang der Zahlung =====
Nach Beendigung der iDEAL Zahlung erhalten Sie einen GET-Request an die im Parameter //urlNotify// angegebene URL. Bitte nutzen Sie diese Meldung, um z.B. den Status der Bestellung zu ändern und eine Bestellbestätigung zu verschicken. 

=== Anfrage ===
**URL:** notifyUrl aus dem Transaktionsstart \\
**Bereitzustellen von:** Händler \\
**Aufzurufen von:** GiroSolution AG

== GET Parameter ==
^Name             ^Pflicht  ^Type        ^Beschreibung   ^
|gcReference      |Ja       |String      |Eindeutige GiroCheckout Transaktions-ID |
|gcMerchantTxId   |Ja       |String      |Transaktions-ID des Händlers |
|gcBackendTxId    |Ja       |String      |iDEAL Transaktions-ID |
|gcAmount         |Ja       |Integer     |Betrag in Cent |
|gcCurrency       |Ja       |String      |Währung |
|gcResultPayment  |Optional |Integer     |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der iDEAL Zahlung]]|
|gcHash           |Ja       |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |

=== Antwort ===
Als Antwort auf den GET-Request wird einer der folgendes HTTP Statuscodes erwartet.

^HTTP Statuscode    ^Beschreibung     ^
|200 (OK)           |Die Benachrichtigung wurde korrekt verarbeitet. |
|400 (Bad Request)  |Der Shop hat die Benachrichtigung nicht verarbeitet, möchte aber auch nicht erneut benachrichtigt werden. |
|Alle anderen       |Die Benachrichtigung wird max. 10 Mal alle 30 Minuten wiederholt, bis der Shop den HTTP Statuscode 200 oder 400 zurückgibt. |
===== Rückleitung des Kunden zum Shop =====
Nach Beendigung der iDEAL Zahlung wird der Kunde an die //urlRedirect// weitergeleitet.

=== Anfrage ===
**URL:** redirectUrl aus dem Transaktionsstart \\
**Bereitzustellen von:** Händler \\
**Aufzurufen von:** GiroSolution AG

== GET Parameter ==
^Name             ^Pflicht  ^Type        ^Beschreibung   ^
|gcReference      |Ja       |String      |Eindeutige GiroCheckout Transaktions-ID |
|gcMerchantTxId   |Ja       |String      |Transaktions-ID des Händlers |
|gcBackendTxId    |Ja       |String      |iDEAL Transaktions-ID |
|gcAmount         |Ja       |Integer     |Betrag in Cent |
|gcCurrency       |Ja       |String      |Währung |
|gcResultPayment  |Optional |Integer     |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der iDEAL Zahlung]]|
|gcHash           |Ja       |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |