girocheckout:giropay:start
Unterschiede
Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
| Beide Seiten der vorigen Revision Vorhergehende Überarbeitung Nächste Überarbeitung | Vorhergehende Überarbeitung | ||
|
girocheckout:giropay:start [2020/04/17 17:49] michaelheumann |
girocheckout:giropay:start [2024/06/05 18:24] (aktuell) michaelheumann |
||
|---|---|---|---|
| Zeile 1: | Zeile 1: | ||
| ~~NOCACHE~~ | ~~NOCACHE~~ | ||
| - | ====== giropay | + | ====== giropay ====== |
| - | + | ||
| - | Informationen zu giropay sind unter https:// | + | |
| giropay kann **ausschließlich** mit der Währung **EURO** verwendet werden. | giropay kann **ausschließlich** mit der Währung **EURO** verwendet werden. | ||
| - | Bitte verwenden Sie für Tests ausschließlich das giropay | + | |
| + | <WRAP center round info 70%> | ||
| + | **Wichtiger Hinweis** \\ | ||
| + | In den nächsten Monaten stellen wir voraussichtlich schrittweise unsere Unterstützung | ||
| + | </ | ||
| + | |||
| + | |||
| + | |||
| + | <WRAP center round info 70%> | ||
| + | **Änderung an der API** \\ | ||
| + | Folgende Änderung an der API wird in diesen Tagen durchgeführt: | ||
| + | Der Parameter merchantReconciliationReferenceNumber wird ersetzt durch merchantOrderReferenceNumber, | ||
| + | </ | ||
| ===== Testdaten giropay ===== | ===== Testdaten giropay ===== | ||
| - | {{page> | + | {{page> |
| + | |||
| + | ===== Transaktionstypen ===== | ||
| + | Detaillierte Informationen zu den [[girocheckout: | ||
| + | |||
| + | < | ||
| + | left to right direction | ||
| + | skinparam packageStyle rect | ||
| + | |||
| + | rectangle SALE{ | ||
| + | (SALE) --> (REFUND) | ||
| + | (REFUND) | ||
| + | } | ||
| + | rectangle AUTH { | ||
| + | (AUTH) --> (CAPTURE ) | ||
| + | (CAPTURE ) --> (REFUND ) | ||
| + | |||
| + | } | ||
| + | </ | ||
| ===== Workflow ===== | ===== Workflow ===== | ||
| Zeile 25: | Zeile 54: | ||
| customer -> shop: | customer -> shop: | ||
| - | shop -> girocheckout: | ||
| - | girocheckout -> shop: | ||
| shop -> girocheckout: | shop -> girocheckout: | ||
| girocheckout -> giropay: | girocheckout -> giropay: | ||
| Zeile 32: | Zeile 59: | ||
| girocheckout -> shop: | girocheckout -> shop: | ||
| shop -> customer: | shop -> customer: | ||
| - | customer -> bank: | + | customer |
| + | giropay | ||
| bank -> customer: | bank -> customer: | ||
| customer -> bank: | customer -> bank: | ||
| Zeile 45: | Zeile 73: | ||
| - | center footer (c)2013 by GiroSolution AG | + | center footer (c)2022 by GiroSolution AG |
| </ | </ | ||
| - | - Käufer/ | + | - Käufer/ |
| - | - Shop prüft Bankstatus ([[girocheckout: | + | - Shop initiiert giropay Transaktion ([[girocheckout: |
| - | - Shop bekommt Rückmeldung, | + | |
| - | - Shop initiiert giropay/ | + | |
| - GiroCheckout initialisiert Transaktion bei giropay | - GiroCheckout initialisiert Transaktion bei giropay | ||
| - giropay übermittelt Ergebnis an GiroCheckout | - giropay übermittelt Ergebnis an GiroCheckout | ||
| - 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-/ | - Shop sendet Redirect URL an Käufer-/ | ||
| - | - Käufer-/ | + | - Käufer-/ |
| + | - giropay leitet dann an das Online-Banking | ||
| - Online-Banking zeigt Loginseite an | - Online-Banking zeigt Loginseite an | ||
| - Käufer/ | - Käufer/ | ||
| Zeile 68: | Zeile 95: | ||
| - Käufer/ | - Käufer/ | ||
| - | ===== API-Funktionen ===== | ||
| - | ==== Übersicht ===== | + | ==== Reservieren (AUTH) |
| + | {{page> | ||
| + | < | ||
| + | left to right direction | ||
| + | skinparam packageStyle rect | ||
| - | Wie im Workflow dargestellt, | + | rectangle AUTH { |
| + | (AUTH) | ||
| + | (AUTH) | ||
| + | } | ||
| + | </ | ||
| - | - Bankstatus prüfen | + | ==== Reservieren/ |
| - | - Transaktion initiieren | + | {{page> |
| - | - Bezahlinformation an Händler übermitteln | + | <uml> |
| - | - Bezahlinformation mit Käuferbrowserweiterleitung zurück zum Händler (durch Käufer nach Zahlung ausgelöst) | + | left to right direction |
| + | skinparam packageStyle rect | ||
| - | Im Folgenden werden die API-Felder und Aufrufe näher erleutert. | + | rectangle SALE{ |
| + | (SALE) | ||
| + | } | ||
| + | </ | ||
| - | ==== Bankstatus prüfen ==== | ||
| - | **Dieser Aufruf sollte nicht mehr verwendet werden, alle giropay-Transaktionen werden jetzt mit einer externen Bankenabfrage durchgeführt!** | ||
| - | Es wird geprüft ob eine Bank am giropay Bezahlverfahren oder einer giropay-ID Abfrage teilnimmt. Diesbezüglich wird die BIC des Käufer-Girokontos übermittelt. Die Antwort zeigt ob eine giropay Transaktion oder giropay-ID Abfrage möglich ist. Es wid empfohlen vor jeder Initiierung einer giropay Transaktion oder giropay-ID Abfrage den Bankstatus zu prüfen, da dadurch unnötige Verkaufsabbrüche verhindert werden können. | + | ===== API-Funktionen ===== |
| - | === API-Aufruf | + | ==== Übersicht ===== |
| - | **URL:** https:// | + | |
| - | **Bereitzustellen von:** GiroCheckout \\ | + | |
| - | **Aufzurufen von:** Händler | + | |
| - | == POST-Parameter == | + | Wie im Workflow dargestellt, gibt es mehrere API-Aufrufe während einer giropay |
| - | ^Name | + | |
| - | |merchantId | + | |
| - | |projectId | + | |
| - | |bic |Ja | + | |
| - | |hash | + | |
| - | == Beispiel == | + | - Transaktion initiieren |
| - | {{page> | + | - Bezahlinformation an Händler übermitteln |
| + | - Bezahlinformation mit Käuferbrowserweiterleitung zurück zum Händler (durch Käufer nach Zahlung ausgelöst oder automatisch nach einigen Sekunden) | ||
| - | === Antwort === | + | Im Folgenden werden |
| - | Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode. Wird **rc = 0** zurückgeliefert, | + | |
| - | + | ||
| - | == JSON-Parameter == | + | |
| - | ^Name | + | |
| - | |rc | + | |
| - | |msg |Ja | + | |
| - | |bankcode | + | |
| - | |bic |Optional |String | + | |
| - | |bankname | + | |
| - | |giropay | + | |
| - | |giropayid | + | |
| - | ^HEADER Parameter^^^^ | + | |
| - | |hash | + | |
| - | + | ||
| - | == Beispiel im Erfolgsfall == | + | |
| - | {{page> | + | |
| - | + | ||
| - | == Beispiel im Fehlerfall == | + | |
| - | {{page> | + | |
| - | + | ||
| - | ==== giropay Bankenabfrage ==== | + | |
| - | **Dieser Aufruf sollte nicht mehr verwendet werden, alle giropay-Transaktionen werden jetzt mit einer externen Bankenabfrage durchgeführt!** | + | |
| - | + | ||
| - | Gibt eine Liste zurück, welche alle giropay Banken enthält. Aus dieser Bankenliste muss der Käufer seine Bank auswählen. | + | |
| - | + | ||
| - | **URL:** https:// | + | |
| - | **Bereitzustellen von:** GiroSolution AG \\ | + | |
| - | **Aufzurufen von:** Händler | + | |
| - | + | ||
| - | == POST Parameter == | + | |
| - | ^Name | + | |
| - | |merchantId | + | |
| - | |projectId | + | |
| - | |hash | + | |
| - | + | ||
| - | == Beispiel == | + | |
| - | {{page> | + | |
| - | + | ||
| - | === Antwort === | + | |
| - | Die Antwort enthält ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, enthält das Element **issuer** die zur Verfügung stehenden Banken. | + | |
| - | + | ||
| - | == Parameter == | + | |
| - | ^Name | + | |
| - | |rc | + | |
| - | |msg |Ja | + | |
| - | |issuer | + | |
| - | ^HEADER Parameter^^^^ | + | |
| - | |hash | + | |
| - | + | ||
| - | == Beispiel == | + | |
| - | {{page> | + | |
| ==== Initialisierung einer giropay Zahlung ==== | ==== Initialisierung einer giropay Zahlung ==== | ||
| - | |||
| - | Die Initialisierung einer giropay Zahlung kann mit oder ohne der Altersverifikation (giropay-ID) stattfinden. Diese Unterscheidung wird ausschließlich anhand der übermittelten projectId getroffen. | ||
| Durch eine erfolgreiche Initialisierung wird eine Referenznummer erstellt sowie ein Weiterleitunslink (redirect) an den Händler übermittelt. Der übermittelte Link führt zum Onlinebanking des Käufers. Er muss an diese URL weitergeleitet werden. Dies kann durch einen HTTP-Redirect-Header, | Durch eine erfolgreiche Initialisierung wird eine Referenznummer erstellt sowie ein Weiterleitunslink (redirect) an den Händler übermittelt. Der übermittelte Link führt zum Onlinebanking des Käufers. Er muss an diese URL weitergeleitet werden. Dies kann durch einen HTTP-Redirect-Header, | ||
| Zeile 167: | Zeile 143: | ||
| == POST Parameter == | == POST Parameter == | ||
| - | ^Name | + | ^Name |
| - | ^ | + | |merchantId |
| - | |merchantId | + | |projectId |
| - | |projectId | + | |merchantTxId |
| - | |merchantTxId | + | |amount |
| - | |amount | + | |currency |
| - | |currency | + | |purpose |
| - | |purpose | + | |type |Optional |
| - | |bic | + | |shoppingCartType |Optional |
| - | |iban |Optional |Optional |Optional | + | |shippingAddresseFirstName |(s. Beschr.) |String(100) | Vorname des Addressaten, **Pflicht** bei Warenkorbtypen PHYSICAL, DIGITAL und MIXED, optional bei ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen: Alle Buchstaben |
| - | |info1Label|Optional |Optional | + | |shippingAddresseLastName |
| - | |info1Text |Optional |Optional | + | |shippingCompany |
| - | |info2Label|Optional |Optional | + | |shippingAdditionalAddressInformation |
| - | |info2Text |Optional |Optional | + | |shippingStreet |
| - | |info3Label|Optional | + | |shippingStreetNumber |
| - | |info3Text | + | |shippingZipCode |
| - | |info4Label|Optional |Optional |Optional | + | |shippingCity |
| - | |info4Text |Optional |Optional | + | |shippingCountry |
| - | |info5Label|Optional |Optional | + | |shippingEmail |
| - | |info5Text |Optional |Optional | + | |merchantOrderReferenceNumber |
| - | |urlRedirect | + | |cart |Optional |
| - | |urlNotify | + | |deliveryType |
| - | |hash |Ja | + | |urlRedirect |
| - | + | |urlNotify | |
| - | + | |kassenzeichen | |
| - | <WRAP center round info 60%> | + | |giropayCustomerId |
| - | Mit den info Parametern können zusätzliche Informationen auf den giropay Überweisungsseiten angezeigt werden. Es sind max. 5 Elemente möglich. Eine Information besteht immer aus einem Label und einer Information. | + | |hash |
| - | </ | + | |
| Zeile 206: | Zeile 181: | ||
| ^Name | ^Name | ||
| |rc | |rc | ||
| - | |msg |Ja | + | |msg |Ja |
| - | |reference | + | |reference |
| - | |redirect | + | |redirect |
| ^HEADER Parameter^^^^ | ^HEADER Parameter^^^^ | ||
| - | |hash | + | |hash |
| == Beispiel im Erfolgsfall == | == Beispiel im Erfolgsfall == | ||
| Zeile 217: | Zeile 192: | ||
| == Beispiel im Fehlerfall == | == Beispiel im Fehlerfall == | ||
| {{page> | {{page> | ||
| + | |||
| + | ==== SEPA-konforme Zeichen ==== | ||
| + | {{page> | ||
| + | |||
| + | === cart-Element === | ||
| + | JSON Array mit item Objekten | ||
| + | |||
| + | ^Name | ||
| + | |name | ||
| + | |ean |Optional | ||
| + | |quantity | ||
| + | |grossAmount | ||
| + | |||
| + | == Beispiel == | ||
| + | < | ||
| + | [ { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } ] | ||
| + | </ | ||
| ==== Benachrichtigung über den Zahlungsausgang ==== | ==== Benachrichtigung über den Zahlungsausgang ==== | ||
| Zeile 222: | Zeile 223: | ||
| Der Ausgang einer giropay-Zahlung wird an die im // | Der Ausgang einer giropay-Zahlung wird an die im // | ||
| - | Der Zahlungausgang der giropay Transaktion steht im Feld gcResultPayment. Wurde zusätzlich die giropay-ID-Überprüfung angefordert, | + | Der Zahlungausgang der giropay Transaktion steht im Feld gcResultPayment. |
| - | Aufgrund | + | Am Ende des Bezahlvorganges auf giropay-Seite findet |
| Zeile 233: | Zeile 234: | ||
| == GET Parameter == | == GET Parameter == | ||
| - | ^Name | + | ^Name |
| - | ^ | + | |gcReference |
| - | |gcReference | + | |gcMerchantTxId |
| - | |gcMerchantTxId | + | |gcBackendTxId |
| - | |gcBackendTxId | + | |gcAmount |
| - | |gcAmount | + | |gcCurrency |
| - | |gcCurrency | + | |gcResultPayment |
| - | |gcResultPayment | + | |gcHash |
| - | |gcResultAVS | + | |
| - | |gcObvName | + | |
| - | |gcHash | + | |
| === Antwort === | === Antwort === | ||
| Zeile 254: | Zeile 252: | ||
| ==== Rückleitung des Kunden zum Händler ==== | ==== Rückleitung des Kunden zum Händler ==== | ||
| - | Nach Beendigung der giropay Zahlung kann der Kunde über einen Link zurück zum Händler kommen. | + | Nach Beendigung der giropay Zahlung kann der Kunde über einen Link zurück zum Händler kommen. |
| === Anfrage === | === Anfrage === | ||
| Zeile 264: | Zeile 262: | ||
| ^Name | ^Name | ||
| ^ | ^ | ||
| - | |gcReference | + | |gcReference |
| - | |gcMerchantTxId | + | |gcMerchantTxId |
| - | |gcBackendTxId | + | |gcBackendTxId |
| |gcAmount | |gcAmount | ||
| - | |gcCurrency | + | |gcCurrency |
| - | |gcResultPayment | + | |gcResultPayment |
| - | |gcResultAVS | + | |gcHash |
| - | |gcObvName | + | |
| - | |gcHash | + | |
| ===== Senderinformationen abrufen ===== | ===== Senderinformationen abrufen ===== | ||
| Zeile 298: | Zeile 294: | ||
| ^Name | ^Name | ||
| |rc | |rc | ||
| - | |msg |Ja | + | |msg |Ja |
| - | |accountholder | + | |accountholder |
| - | |iban | + | |iban |
| - | |bic |Optional |String | + | |bic |Optional |String(11) |
| ^HEADER Parameter^^^^ | ^HEADER Parameter^^^^ | ||
| - | |hash | + | |hash |
| == Beispiel im Erfolgsfall == | == Beispiel im Erfolgsfall == | ||
| Zeile 311: | Zeile 307: | ||
| {{page> | {{page> | ||
| + | ===== Weitere Transaktionsarten ===== | ||
| + | Diese Transaktionen verweisen (referenzieren) auf eine zuvor erfolgte Transaktion. Die Transaktion basiert auf einer Server-zu-Server-Kommunikation und erfordert keine Kundenaktion (Eingabe von Daten). | ||
| + | |||
| + | Bereitzustellen von: GiroCheckout \\ | ||
| + | Aufzurufen von: Händler \\ | ||
| + | |||
| + | ==== Workflow ==== | ||
| + | |||
| + | <uml> | ||
| + | hide footbox | ||
| + | |||
| + | participant " | ||
| + | participant " | ||
| + | participant " | ||
| + | |||
| + | autonumber | ||
| + | |||
| + | shop -> girocheckout: | ||
| + | girocheckout -> gp: | ||
| + | gp -> girocheckout: | ||
| + | girocheckout -> shop: | ||
| + | |||
| + | center footer (c)2024 by S-Public Services GmbH | ||
| + | </ | ||
| + | |||
| + | - Shop sendet referenzierende Transaktion | ||
| + | - GiroCheckout leitet Transaktion zu giropay | ||
| + | - giropay übermittelt Ergebnis an GiroCheckout | ||
| + | - Shop bekommt Rückmeldung über Transaktionsausgang ([[girocheckout: | ||
| + | |||
| + | ==== Buchen (CAPTURE) ==== | ||
| + | {{page> | ||
| + | |||
| + | <uml> | ||
| + | left to right direction | ||
| + | skinparam packageStyle rect | ||
| + | |||
| + | rectangle AUTH { | ||
| + | (auth) --> (CAPTURE) | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== Erstattung (REFUND) ==== | ||
| + | {{page> | ||
| + | <uml> | ||
| + | left to right direction | ||
| + | skinparam packageStyle rect | ||
| + | |||
| + | rectangle SALE{ | ||
| + | (sale) --> (REFUND) | ||
| + | } | ||
| + | rectangle AUTH { | ||
| + | (auth) --> (REFUND ) | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | === POST Parameter === | ||
| + | URL CAPTURE: https:// | ||
| + | URL REFUND: https:// | ||
| + | |||
| + | ^Name | ||
| + | ^::: ^ CAPTURE ^ REFUND ^::: ^::: ^ | ||
| + | |merchantId | ||
| + | |projectId | ||
| + | |merchantTxId | ||
| + | |amount | ||
| + | |currency | ||
| + | |purpose | ||
| + | |reference | ||
| + | |merchantReconciliationReferenceNumber |Optional |Optional | ||
| + | |final | ||
| + | |kassenzeichen | ||
| + | |hash | ||
| + | |||
| + | == Beispiel == | ||
| + | {{page> | ||
| + | |||
| + | === Antwort === | ||
| + | Die Antwort besteht aus einem JSON Objekt. Das Feld resultPayment liefert einen Fehlercode zurück. Wird resultPayment = 4000 zurückgeliefert, | ||
| + | |||
| + | == Parameter == | ||
| + | ^Name | ||
| + | |rc | ||
| + | |msg |Ja | ||
| + | |reference | ||
| + | |merchantTxId | ||
| + | |backendTxId | ||
| + | |amount | ||
| + | |currency | ||
| + | |resultPayment | ||
| + | |hash | ||
| + | |||
| + | == Beispiel im Erfolgsfall == | ||
| + | {{page> | ||
| + | |||
| + | == Beispiel im Fehlerfall == | ||
| + | {{page> | ||
| + | |||
| + | ==== Stornierung (VOID) ==== | ||
| + | {{page> | ||
| + | |||
| + | === POST Parameter === | ||
| + | URL VOID: https:// | ||
| + | |||
| + | ^Name | ||
| + | |merchantId | ||
| + | |projectId | ||
| + | |merchantTxId | ||
| + | |reference | ||
| + | |hash | ||
| + | |||
| + | == Beispiel == | ||
| + | {{page> | ||
| + | |||
| + | === Antwort === | ||
| + | Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, | ||
| + | |||
| + | == Parameter == | ||
| + | ^Name | ||
| + | |rc | ||
| + | |msg |Ja | ||
| + | |reference | ||
| + | |referenceParent | ||
| + | |merchantTxId | ||
| + | |backendTxId | ||
| + | |amount | ||
| + | |currency | ||
| + | |resultPayment | ||
| + | |hash | ||
| + | |||
| + | == Beispiel im Erfolgsfall == | ||
| + | {{page> | ||
| + | |||
| + | == Beispiel im Fehlerfall == | ||
| + | {{page> | ||
girocheckout/giropay/start.1587138578.txt.gz · Zuletzt geändert: 2021/04/12 14:30