{{indexmenu_n>3}} ====== giropay-ID API Funktionen ====== ===== Bankstatus prüfen ===== Mit dieser Funktion prüfen Sie, ob eine Bank am giropay-ID Verfahren teilnimmt und Altersverifikation/Zahlung abgewickelt werden können. Bitte nutzen Sie vor **jeder** giropay-ID Transaktion diese Funktion, um sicherzustellen, dass die Bank des Kunden die entsprechende giropay-ID Transaktion unterstützt und verfügbar ist. === Anfrage === **URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/bankstatus \\ **Bereitzustellen von:** GiroSolution AG \\ **Aufzurufen von:** Händler == Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |merchantId |Ja |Integer |Händler-ID eines giropay-ID oder giropay-ID + giropay Projekts | |projectId |Ja |Integer |Projekt-ID eines giropay-ID oder giropay-ID + giropay Projekts | |bankcode |Optional |String(8) |Bankleizahl der Kundenbank, die geprüft werden soll | |bic |Optional |String(11)|BIC der Kundenbank, die geprüft werden soll | |hash |Ja |String(32)|HMAC MD5 hash über alle Werte des Aufrufs. Siehe [[girocheckout:general:start#hash_generieren|hash generieren]]| Für die Überprüfung muss entweder die Bankleitzahl oder die BIC der Kundenbank angegeben werden. Werden beide Informationen angegeben, müssen diese zur selben Bank gehören. == Beispiel == {{page>codesamples:giropay#bankstatus.request&noheader&nofooter}} === Antwort === Die Antwort ist ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, kann über die Bank eine giropay-ID Transaktion abgewicklt werden. Zusätzliche Information zur Unterstützung von giropay und giropay-ID können Sie den Elementen //giropay// und //giropayid// entnehmen. Wenn bekannt, wird Ihnen auch der Bankname zurückgegeben. == Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |rc |Ja |Integer |[[girocheckout:errorcodes|Fehlernummer]] | |msg |Ja |String |Zusätzliche Informationen im Fehlerfall | |bankcode |Optional |Integer |Bankleitzahl| |bic |Optional |String |BIC, wenn vorhanden | |bankname |Optional |String |Bankname | |giropay |Optional |Integer |0 = giropay Zahlung wird nicht unterstützt \\ 1 = giropay Zahlung wird unterstützt | |giropayid |Optional |Integer |0 = giropay-ID und giropay-ID + giropay wird nicht unterstützt \\ 1 = giropay-ID und giropay-ID + giropay wird unterstützt | == Beispiel im Erfolgsfall == {{page>codesamples:giropay#bankstatus.response.true&noheader&nofooter}} == Beispiel im Fehlerfall == {{page>codesamples:giropay#bankstatus.response.false&noheader&nofooter}} ===== Initialisierung der giropay-ID 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 durch eine TAN bestätigt. 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 giropay Projekts | |projectId |Ja |integer |Projekt-ID eines giropay 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 giropay Überweisung | |bankcode |Optional |String(8) |Bankleitzahl der Kundenbank | |bankaccount |Optional |String(10) |Kontonummer der Kundenbankverbindung (für eine evtl. Rückabwicklung) | |bic |Optional |String(11) |BIC der Kundenbank | |iban |Optional |String(34) |IBAN der Kundenbankverbindung | |info[1..5]Label|Optional |String(30) |Zusätzliche Information für die giropay Überweisungsseiten (Feldname) | |info[1..5]Text |Optional |String(80) |Zusätzliche Information für die giropay Überweisungsseiten (Information) | |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]] | == Die info Parameter == Mit den info Parametern können Sie zusätzliche Informationen auf den giropay Überweisungsseiten anzeigen. Es sind max. 5 Elemente möglich. Eine Information besteht immer aus einem Label und einer Information. == Beispiel == {{page>codesamples:giropay#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:giropay#transactionstart.response.true&noheader&nofooter}} == Beispiel im Fehlerfall == {{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}} ===== Benachrichtigung über den Ausgang der Zahlung ===== Nach Beendigung der giropay Zahlung/Altersverifikation 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. Aufgrund des giropay Ablaufes findet eine Rückleitung des Kunden an die //urlRedirect// nicht automatisch statt, sondern nur nach einem Klick durch den Kunden. === 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 |giropay Transaktions-ID | |gcAmount |Ja |Integer |Betrag in Cent | |gcCurrency |Ja |String |Währung | |gcResultPayment |Optional |Integer |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der giropay Zahlung]]| |gcResultAVS |Optional |Integer |[[girocheckout:resultcodes#altersverifikation|Ergebnis der giropay Altersverifikation]] | |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 giropay Zahlung kann der Kunde über einen Link zurück zum Shop kommen. Diese Rückleitung erfolgt nicht automatisch. === 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 |giropay Transaktions-ID | |gcAmount |Ja |Integer |Betrag in Cent | |gcCurrency |Ja |String |Währung | |gcResultPayment |Optional |Integer |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der giropay Zahlung]]| |gcResultAVS |Optional |Integer |[[girocheckout:resultcodes#altersverifikation|Ergebnis der giropay Altersverifikation]] | |gcHash |Ja |String |HMAC MD5 hash über alle Werte des Aufrufs. Siehe [[girocheckout:general:start#hash_generieren|hash generieren]] |