Girocheckout API

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Zuletzt angesehen:
girocheckout:eps:start

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen Revision Vorhergehende Überarbeitung
Nächste Überarbeitung 		Vorhergehende Überarbeitung
girocheckout:eps:start [2018/07/02 21:58]
thorstenmarx [Initialisierung einer eps Zahlung] 		girocheckout:eps:start [2023/05/05 03:19] (aktuell)
michaelheumann
Zeile 1: Zeile 1:
 ~~NOCACHE~~ ~~NOCACHE~~
 ====== eps ====== ====== eps ======
- 
-Informationen zu eps sind unter https://www.girosolution.de/girocheckout/fuer-haendler/ zu finden. 
  
 eps kann **ausschließlich** mit der Währung **EURO** verwendet werden. eps kann **ausschließlich** mit der Währung **EURO** verwendet werden.
Zeile 22: Zeile 20:
 autonumber autonumber
  
-customer -> shop:  +customer -> shop:
-shop -> girocheckout:  +
-girocheckout -> shop: +
 shop -> girocheckout: shop -> girocheckout:
 girocheckout -> eps:  girocheckout -> eps: 
Zeile 30: Zeile 26:
 girocheckout -> shop:  girocheckout -> shop: 
 shop -> customer:  shop -> customer: 
-customer -> bank:+customer -> eps: 
 +eps -> bank:
 bank -> customer:  bank -> customer: 
 customer -> bank: customer -> bank:
Zeile 47: Zeile 44:
  
   - Käufer/Kunde wählt eps und gibt BIC seiner Bank ein   - Käufer/Kunde wählt eps und gibt BIC seiner Bank ein
-  - Shop prüft Bankstatus ([[girocheckout:eps:start#bankstatus_prüfen|Bankstatus prüfen]]) 
-  - Shop bekommt Rückmeldung, ob Bank eps unterstützt 
   - Shop initiiert eps Transaktion ([[girocheckout:eps:start#initialisierung_einer_eps_zahlung|Initialisierung]])   - Shop initiiert eps Transaktion ([[girocheckout:eps:start#initialisierung_einer_eps_zahlung|Initialisierung]])
   - GiroCheckout initialisiert Transaktion bei eps   - GiroCheckout initialisiert Transaktion bei eps
Zeile 54: Zeile 49:
   - Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)   - Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)
   - Shop sendet Redirect URL an Käufer-/Kundenbrowser    - Shop sendet Redirect URL an Käufer-/Kundenbrowser 
-  - Käufer-/Kundenbrowser leitet zum Online-Banking weiter+  - Käufer-/Kundenbrowser leitet zu eps weiter, wo die Bankauswahl erfolgt (optional, falls nicht schon im Browser gesp[eichert) 
 +  - eps leitet dann an das Online-Banking der entsprechenden Bank weiter
   - Online-Banking zeigt Loginseite an   - Online-Banking zeigt Loginseite an
   - Käufer/Kunde autorisiert Transaktion   - Käufer/Kunde autorisiert Transaktion
Zeile 78: Zeile 74:
  
 Im Folgenden werden die API-Felder und Aufrufe näher erleutert. Im Folgenden werden die API-Felder und Aufrufe näher erleutert.
 +
 ==== Bankstatus prüfen ==== ==== Bankstatus prüfen ====
 +**Dieser Aufruf sollte nicht mehr verwendet werden, alle eps-Transaktionen werden jetzt mit einer externen Bankenabfrage durchgeführt!**
 +
 Es wird geprüft ob eine Bank am eps Bezahlverfahren teilnimmt. Diesbezüglich wird die BIC des Käufer-Girokontos übermittelt. Die Antwort zeigt ob eine eps Transaktion möglich ist. Es wid empfohlen vor jeder Initiierung einer eps Transaktion den Bankstatus zu prüfen, da dadurch unnötige Verkaufsabbrüche verhindert werden können. Es wird geprüft ob eine Bank am eps Bezahlverfahren teilnimmt. Diesbezüglich wird die BIC des Käufer-Girokontos übermittelt. Die Antwort zeigt ob eine eps Transaktion möglich ist. Es wid empfohlen vor jeder Initiierung einer eps Transaktion den Bankstatus zu prüfen, da dadurch unnötige Verkaufsabbrüche verhindert werden können.
  
Zeile 90: Zeile 89:
 |merchantId     |Ja       |Integer   |Händler-ID eines eps Projekts | |merchantId     |Ja       |Integer   |Händler-ID eines eps Projekts |
 |projectId      |Ja       |Integer   |Projekt-ID eines eps Projekts | |projectId      |Ja       |Integer   |Projekt-ID eines eps Projekts |
-|bic            |Ja       |String(11)|BIC der Käuferbank (8 oder 11-stellig), die geprüft werden soll (durch [[tools:bankstatus_widget|Bankauswahl Widget]] ermittelbar)|+|bic            |Ja       |String(11)|BIC der Käuferbank (8 oder 11-stellig), 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]])| |hash           |Ja       |String(32)|HMAC MD5 hash über alle Werte des Aufrufs (siehe [[girocheckout:general:start#hash_generieren|hash generieren]])|
  
Zeile 101: Zeile 100:
 == JSON-Parameter == == JSON-Parameter ==
 ^Name           ^Pflicht  ^Type      ^Beschreibung   ^ ^Name           ^Pflicht  ^Type      ^Beschreibung   ^
-|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | +|rc             |Ja       |Integer    |[[girocheckout:errorcodes|Fehlernummer]] | 
-|msg            |Ja       |String    |zusätzliche Informationen im Fehlerfall | +|msg            |Ja       |String(255)|zusätzliche Informationen im Fehlerfall | 
-|bankcode       |Optional |Integer   |Bankleitzahl| +|bankcode       |Optional |Integer    |Bankleitzahl| 
-|bic            |Optional |String    |BIC, wenn vorhanden | +|bic            |Optional |String(11) |BIC, wenn vorhanden | 
-|bankname       |Optional |String    |Bankname | +|bankname       |Optional |String(100)|Bankname | 
-|eps        |Optional |Integer   |0 = eps Zahlung wird nicht unterstützt \\ 1 = eps Zahlung wird unterstützt |+|eps            |Optional |Integer    |0 = eps Zahlung wird nicht unterstützt \\ 1 = eps Zahlung wird unterstützt |
 ^HEADER Parameter^^^^ ^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]] |+|hash           |Ja       |String(32) |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]] |
  
 == Beispiel im Erfolgsfall == == Beispiel im Erfolgsfall ==
Zeile 114: Zeile 113:
  
 ==== eps Bankenabfrage ==== ==== eps Bankenabfrage ====
 +**Dieser Aufruf sollte nicht mehr verwendet werden, alle eps-Transaktionen werden jetzt mit einer externen Bankenabfrage durchgeführt!**
 +
 Gibt eine Liste zurück, welche alle eps Banken enthält. Aus dieser Bankenliste muss der Käufer seine Bank auswählen.  Gibt eine Liste zurück, welche alle eps Banken enthält. Aus dieser Bankenliste muss der Käufer seine Bank auswählen. 
  
Zeile 134: Zeile 135:
 == Parameter == == Parameter ==
 ^Name           ^Pflicht  ^Type      ^Beschreibung   ^ ^Name           ^Pflicht  ^Type      ^Beschreibung   ^
-|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | +|rc             |Ja       |Integer    |[[girocheckout:errorcodes|Fehlernummer]] | 
-|msg            |Ja       |String    |Zusätzliche Informationen im Fehlerfall | +|msg            |Ja       |String(255)|Zusätzliche Informationen im Fehlerfall | 
-|issuer         |Optional |Array     |Liste der eps issuer Banken bestehend aus dem Key BIC und dem Bankname |+|issuer         |Optional |Array      |Liste der eps issuer Banken bestehend aus dem Key BIC und dem Bankname |
 ^HEADER Parameter^^^^ ^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]] |+|hash           |Ja       |String(32) |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]] |
  
 == Beispiel == == Beispiel ==
Zeile 156: Zeile 157:
 |merchantId     |Ja       |Integer     |Händler-ID eines eps Projekts | |merchantId     |Ja       |Integer     |Händler-ID eines eps Projekts |
 |projectId      |Ja       |integer     |Projekt-ID eines eps Projekts | |projectId      |Ja       |integer     |Projekt-ID eines eps Projekts |
-|merchantTxId   |Ja       |String(255) |eindeutige Transaktions-ID des Händlers |+|merchantTxId   |Ja       |String(255) |eindeutige Transaktions-ID des Händlers. Zulässige Zeichen: beliebige Buchstaben (inkl. sprachl. Sonderzeichen), 0-9, Zeichen & = + , : ; . _ ! ? # /  |
 |amount         |Ja       |Integer     |Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny | |amount         |Ja       |Integer     |Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny |
 |currency       |Ja       |String(3)   |Währung der Transaktion\\ EUR = Euro| |currency       |Ja       |String(3)   |Währung der Transaktion\\ EUR = Euro|
 |purpose        |Ja       |String(27)  |Verwendungszweck der eps Überweisung | |purpose        |Ja       |String(27)  |Verwendungszweck der eps Überweisung |
-|bic            |Optional |String(11)  |BIC der Käuferbank (8 oder 11-stellig) (durch [[tools:bankstatus_widget|Bankauswahl Widget]] ermittelbar)| +|bic            |**deprecated** |String(11)  |**Dieser Parameter darf nicht mehr verwendet werden, alle eps-Transaktionen werden jetzt mit einer externen Bankenabfrage durchgeführt!** BIC der Käuferbank (8 oder 11-stellig)| 
-|urlRedirect    |Ja       |String      |URL, an die der Kunde nach der Zahlung geschickt werden soll. | +|urlRedirect    |Ja       |String(2048) |URL, an die der Kunde nach der Zahlung geschickt werden soll. | 
-|urlNotify      |Ja       |String      |URL, an die der Zahlungsausgang gemeldet werden soll. | +|urlNotify      |Ja       |String(2048) |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]] |+|kassenzeichen  |Optional |String(255)  |Optionales Feld für die Übergabe eines Kassenzeichens.  Dieses wird dann im GiroCockpit in den Transaktionsdetails angezeigt (und bald auch exportiert) und es kann dort auch danach gesucht werden.  Zulässige Zeichen sind alle UTF-8-Zeichen. | 
 +|hash           |Ja       |String(32) |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |
  
  
Zeile 175: Zeile 177:
 ^Name           ^Pflicht  ^Type      ^Beschreibung   ^ ^Name           ^Pflicht  ^Type      ^Beschreibung   ^
 |rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | |rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] |
-|msg            |Ja       |String    |zusätzliche Informationen im Fehlerfall | +|msg            |Ja       |String(255)|zusätzliche Informationen im Fehlerfall | 
-|reference      |Optional |String    |eindeutige GiroCheckout Transaktions-ID | +|reference      |Optional |String(36) |eindeutige GiroCheckout Transaktions-ID | 
-|redirect       |Optional |String    |Redirect URL zur Weiterleitung des Kunden an sein Online Banking|+|redirect       |Optional |String(2048) |Redirect URL zur Weiterleitung des Kunden an sein Online Banking|
 ^HEADER Parameter^^^^ ^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]] |+|hash           |Ja       |String(32) |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]] |
  
 == Beispiel im Erfolgsfall == == Beispiel im Erfolgsfall ==
Zeile 203: Zeile 205:
 == GET Parameter == == GET Parameter ==
 ^Name           ^Pflicht  ^Type        ^Beschreibung   ^ ^Name           ^Pflicht  ^Type        ^Beschreibung   ^
-|gcReference      |Ja      |String      | GiroCheckout Transaktions-ID | +|gcReference      |Ja      |String(36)  | GiroCheckout Transaktions-ID | 
-|gcMerchantTxId   |Ja      |String      | Händler Transaktions-ID | +|gcMerchantTxId   |Ja      |String(255) | Händler Transaktions-ID | 
-|gcBackendTxId    |Ja      |String      | Zahlungsabwickler Transaktions-ID |+|gcBackendTxId    |Ja      |String(10)  | Zahlungsabwickler Transaktions-ID |
 |gcAmount         |Ja      |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent | |gcAmount         |Ja      |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent |
-|gcCurrency       |Ja      |String      | Währung |+|gcCurrency       |Ja      |String(3)   | Währung |
 |gcResultPayment  |Ja      |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebniscodes der eps Zahlung]]| |gcResultPayment  |Ja      |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebniscodes der eps Zahlung]]|
-|gcHash           |Ja      |String      | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |+|gcHash           |Ja      |String(32) | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |
  
 === Antwort === === Antwort ===
Zeile 229: Zeile 231:
 == GET Parameter == == GET Parameter ==
 ^Name           ^Pflicht  ^Type        ^Beschreibung   ^ ^Name           ^Pflicht  ^Type        ^Beschreibung   ^
-|gcReference      |Ja  |String      | GiroCheckout Transaktions-ID | +|gcReference      |Ja     |String(36)  | GiroCheckout Transaktions-ID | 
-|gcMerchantTxId   |Ja   |String      | Händler Transaktions-ID | +|gcMerchantTxId   |Ja      |String(255) | Händler Transaktions-ID | 
-|gcBackendTxId    |Ja      |String      | Zahlungsabwickler Transaktions-ID |+|gcBackendTxId    |Ja      |String(10)  | Zahlungsabwickler Transaktions-ID |
 |gcAmount         |Ja      |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent | |gcAmount         |Ja      |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent |
-|gcCurrency       |Ja      |String      | Währung |+|gcCurrency       |Ja      |String(3)   | Währung |
 |gcResultPayment  |Ja      |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebniscodes der eps Zahlung]]| |gcResultPayment  |Ja      |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebniscodes der eps Zahlung]]|
-|gcHash           |Ja      |String      | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |+|gcHash           |Ja      |String(32) | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] | 
 + 
 +===== Senderinformationen abrufen ===== 
 +Mit dieser Funktion können die Senderinformationen einer erfolgreich durchgeführten Transaktion abgerufen werden. Anhand der angegebenen Referenz wird Kontoinhaber, IBAN und BIC des Absenders geliefert.  Diese Information kann dann für eine Rücküberweisung an den Zahler genutzt werden. 
 + 
 +=== API-Aufruf === 
 +**URL:** https://payment.girosolution.de/girocheckout/api/v2/eps/senderinfo \\ 
 +**Bereitzustellen von:** GiroCheckout \\ 
 +**Aufzurufen von:** Händler 
 + 
 +== POST-Parameter == 
 +^Name           ^Pflicht  ^Type      ^Beschreibung   ^ 
 +|merchantId     |Ja       |Integer   |Händler-ID eines eps Projekts | 
 +|projectId      |Ja       |Integer   |Projekt-ID eines eps Projekts | 
 +|reference      |Ja       |String(36)|GiroCheckout Transaktions-ID | 
 +|hash           |Ja       |String(32)|HMAC MD5 hash über alle Werte des Aufrufs (siehe [[girocheckout:general:start#hash_generieren|hash generieren]])| 
 + 
 +== Beispiel == 
 +{{page>codesamples:eps#senderinfo.request&noheader&nofooter}} 
 + 
 +=== Antwort === 
 +Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode. Wird **rc = 0** zurückgeliefert, enthalten die entsprechenden Felder die Senderinformationen. 
 + 
 +== JSON-Parameter == 
 +^Name           ^Pflicht  ^Type      ^Beschreibung   ^ 
 +|rc             |Ja       |Integer     |[[girocheckout:errorcodes|Fehlernummer]] | 
 +|msg            |Ja       |String(255) |zusätzliche Informationen im Fehlerfall | 
 +|accountholder  |Optional |String(255) |Inhaber des Absenderkontos| 
 +|iban           |Optional |String(34)  |IBAN des Absenderkontos | 
 +|bic            |Optional |String(11)  |BIC des Absenderkontos | 
 +^HEADER Parameter^^^^ 
 +|hash           |Ja       |String(32) |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]] | 
 + 
 +== Beispiel im Erfolgsfall == 
 +{{page>codesamples:eps#senderinfo.response.true&noheader&nofooter}} 
 + 
 +== Beispiel im Fehlerfall == 
 +{{page>codesamples:eps#senderinfo.response.false&noheader&nofooter}}
  
-===== Bankauswahl Widget ===== 
-{{page>girocheckout:widget&noheader&nofooter}} 
girocheckout/eps/start.1530561538.txt.gz · Zuletzt geändert: 2021/04/12 14:30

Seiten-Werkzeuge