{{indexmenu_n>3}} ====== Lastschrift API Funktionen ====== Die Integration einer Zahlung per Lastschrift kann auf zwei Wege erfolgen. Entweder Sie fragen die notwendigen Daten (IBAN oder Kontonummer und Bankleitzahl) im Shop ab und können die Zahlung über einen Schnittstellenaufruf durchführen oder Sie nutzen den Formularservice. ==== Durchführen einer Lastschrift Zahlung ==== Sie übermitteln die Transaktionsdaten und erhalten direkt das Ergebnis der Lastschrift Zahlung. === Anfrage === **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/payment \\ **Bereitzustellen von:** GiroSolution AG \\ **Aufzurufen von:** Händler == Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |merchantId |Ja |Integer |Händler-ID eines Lastschrift Projekts | |projectId |Ja |integer |Projekt-ID eines Lastschrift Projekts | |merchantTxId |Ja |String(255) |Eindeutige Transaktions-ID des Händlers | |amount |Ja |Integer |Betrag in Cent | |currency |Optional |String(3) |Währung der Transaktion als Währungscode gemäß [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]]\\ EUR = Euro (default) | |purpose |Ja |String(27) |Verwendungszweck der Lastschrift Transaktion. Diese Information erscheint auf dem Kontoauszug. | |bankcode |Optional |String(8) |Bankleitzahl \\ **Plicht, wenn keine IBAN angegeben ist.** | |bankaccount |Optional |String(10) |Kontonummer \\ **Plicht, wenn keine IBAN angegeben ist.** | |iban |Optional |String |IBAN \\ **Plicht, wenn keine Bankleitzahl und Kontonummer angegeben ist.** | |mandateReference | Optional |String(35) |Mandatsreferenz \\ Wird keine angegeben, wird eine eindeutige Mandatsreferenz generiert. Die Manadatsreferenz ist in der Antwort enthalten. | |mandateSignedOn | Optional |String(10)| Datum im Format JJJJ-MM-TT, wann das SEPA-Lastschriftmandat erteilt wurde. Wenn kein Datum angegeben wird, wird das aktuelle Datum verwendet. | |mandateReceiverName |Optional |String(70)| Names des Empfängers, der im SEPA Mandat verwendet wurde. Falls nichts angegeben, wird der in den Stammdaten hinterlegte Firmenname verwendet. | |mandateSequence | Optional |Integer |Sequenztyp der SEPA-Lastschrift. Falls nichts angegeben, wird eine Einmalzahlung angenommen. \\ 1 = Einmalzahlung (default) \\ 2 = Erste Zahlung einer Sequenz \\ 3 = Folgezahlung \\ 4 = Letzte Zahlung einer Sequenz | |hash |Ja |String |HMAC MD5 hash über alle Werte des Aufrufs. Siehe [[girocheckout:general:start#hash_generieren|hash generieren]] | == Beispiel == {{page>codesamples:directdebit#authorize.request&noheader&nofooter}} === Antwort === Die Antwort ist ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, war der Aufruf fehlerfrei und das Ergebnis der Lastschrift Transaktion ist dem Parameter **resultPayment** zu entnehmen. == Parameter == ^Name ^Pflicht ^Type ^Beschreibung ^ |rc |Ja |Integer |Antwortcode | |msg |Ja |String |Zusätzliche Informationen im Fehlerfall | |reference |Optional |String |Eindeutige GiroCheckout Transaktions-ID | |backendTxId |Optional |String |Backend Transaktions-ID | |mandateReference |Optional |String |Mandatsreferenz der SEPA Lastschrift | |resultPayment |Optional |Integer |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der Lastschrift Zahlung]] | == Beispiel im Erfolgsfall == {{page>codesamples:directdebit#authorize.response.true&noheader&nofooter}} == Beispiel im Fehlerfall == {{page>codesamples:directdebit#authorize.response.false&noheader&nofooter}} ====== Lastschrift über Formularservice ====== ===== Initialisierung der Lastschrift 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 das Formular für die Lastschrift Zahlung ausfüllt und 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 und den Kunden nach der Zahlung zu urlRedirect weiterleitet. === 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 Lastschrift Projekts | |projectId |Ja |integer |Projekt-ID eines Lastschrift Projekts | |merchantTxId |Ja |String(255) |Eindeutige Transaktions-ID des Händlers | |amount |Ja |Integer |Betrag in Cent | |currency |Optional |String(3) |Währung der Transaktion als Währungscode gemäß [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]]\\ EUR = Euro (default) | |purpose |Ja |String(27) |Verwendungszweck der Lastschrift Transaktion. Diese Information erscheint auf dem Kontoauszug. | |locale |Optional |String(2) |Sprache des Lastschriftformulars, wenn es angezeigt werden soll. \\ de = deutsch (default) \\ en = englisch \\ es = spanisch \\ fr = französisch \\ it = italienisch \\ pt = portugiesisch \\ nl = niederländisch \\ cs = tschechisch \\ sv = schwedisch \\ da = dänisch \\ pl = polnisch \\ spde = deutsch Spende \\ spen = englisch Spende | |mobile |Optional |Integer |Definiert, ob das Formular für Smartphones und mobile Browser optimiert angezeigt werden soll. \\ 0 = nein (default) \\ 1 = ja | |mandateReference | Optional |String(35) |Mandatsreferenz \\ Wird keine angegeben, wird eine eindeutige Mandatsreferenz generiert. Die Manadatsreferenz ist in der Antwort enthalten. | |mandateSignedOn | Optional |String(10)| Datum im Format JJJJ-MM-TT, wann das SEPA-Lastschriftmandat erteilt wurde. Wenn kein Datum angegeben wird, wird das aktuelle Datum verwendet. | |mandateReceiverName |Optional |String(70)| Names des Empfängers, der im SEPA Mandat verwendet wurde. Falls nichts angegeben, wird der in den Stammdaten hinterlegte Firmenname verwendet. | |mandateSequence | Optional |Integer |Sequenztyp der SEPA-Lastschrift. Falls nichts angegeben, wird eine Einmalzahlung angenommen. \\ 1 = Einmalzahlung (default) \\ 2 = Erste Zahlung einer Sequenz \\ 3 = Folgezahlung \\ 4 = Letzte Zahlung einer Sequenz | |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:directdebit#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 |Antwortcode | |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:directdebit#transactionstart.response.true&noheader&nofooter}} == Beispiel im Fehlerfall == {{page>codesamples:directdebit#transactionstart.response.false&noheader&nofooter}} ===== Benachrichtigung über den Ausgang der Zahlung ===== Nach Beendigung der Lastschrift 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 |Backend Transaktions-ID | |gcAmount |Ja |Integer |Betrag in Cent | |gcCurrency |Ja |String |Währung | |gcResultPayment |Optional |Integer |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der Lastschrift 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 Lastschrift Zahlung wird der Kunden zurück zum Shop geleitet. === 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 |Backend Transaktions-ID | |gcAmount |Ja |Integer |Betrag in Cent | |gcCurrency |Ja |String |Währung | |gcResultPayment |Optional |Integer |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der Lastschrift Zahlung]]| |gcHash |Ja |String |HMAC MD5 hash über alle Werte des Aufrufs. Siehe [[girocheckout:general:start#hash_generieren|hash generieren]] |