Benutzer-Werkzeuge

Webseiten-Werkzeuge


Übersetzungen dieser Seite:
girocheckout:giropay:start

giropay

giropay kann ausschließlich mit der Währung EURO verwendet werden.

Wichtiger Hinweis
In den nächsten Monaten stellen wir voraussichtlich schrittweise unsere Unterstützung für die bisherige giropay-Schnittstelle (s. alte giropay-Beschreibung) ein. Danach gilt AUSSCHLIEßLICH die hier beschriebene neue Schnittstelle. Falls Sie umsteigen, beachten Sie bitte unseren Migrationsleitfaden auf unserer giropay Übersichtsseite. Dort finden Sie auch einen Vergleich der alten und neuen Schnittstelle.

Änderung an der API
Folgende Änderung an der API wird in diesen Tagen durchgeführt:
Der Parameter merchantReconciliationReferenceNumber wird ersetzt durch merchantOrderReferenceNumber, welcher weiterhin optional ist aber nur 20 Zeichen lang sein darf. Man beachte auch die unten angegebenen Restriktionen bzgl. der zugelassenen Zeichen.

Testdaten giropay

Im Folgenden finden Sie die Testdaten sowohl für giropay ALT (der frühere giropay-Weg über das Online-Banking), als auch für giropay NEU (der frühere Paydirekt-Weg über Login und Passwort).

Welcher Weg (ALT und/oder NEU) Ihnen beim Testen zur Verfügung steht, hängt von Ihrem Vertrag ab. Wenden Sie sich bei Bedarf an Ihren Kundenberater, sollte nicht der erwartete Weg erscheinen. Bedenken Sie aber bitte auch, dass je nach Browser-Einstellung (der sich den Weg i.d.R. merkt) im ersten Augenblick ALT oder NEU angezeigt werden könnte und Sie über die Linkspfeile innerhalb der giropay-Seiten (NICHT zu verwechseln mit dem Browser-Zurück-Knopf!) zur Auswahl des gewünschten Weges gelangen können.

Verwenden Sie bitte die folgenden Logindaten (ändern Sie bitte dort nicht das Passwort und bedenken Sie, dass Ihre Testtransaktionen u.U. auch durch andere testende Kunden eingesehen werden können.):

Formularfeld Eingabewert
Benutzername Giropay_test
Passwort 8x5hHDs+98Q2W
TAN (sollte sie abgefragt werden)123456

giropay ALT

Bitte verwenden Sie für Tests ausschließlich das u.a. giropay Testinstitut!

Formularfeld Eingabewert
Bank giropay Testbank
IBAN DE48499999601234567890
VR-NetKey / Alias(beliebiger Wert)
PIN1234
TAN‑Verfahren auswählen (nur bei Beträgen >= 20,00, s. unten)„Smart-TAN plus optisch / USB“ oder „Smart-TAN photo“
TAN123456

Besondere Beträge

Das Verhalten der Transaktion kann über die Checkoutsumme (Magic-Numbers) gesteuert werden (s.u.). Für die Integration von giropay in einen Shop oder eine Behörde ist vor allem wichtig, dass die u.a. Beträge eine Sonderbehandlung haben und somit bei Nichtbeachtung unerwartete Testergebnisse produzieren können.

Betrag Reaktion
2,00 EURBei PSD2-Zahlung wird die Zahlung von PSD2-Bank sofort mit dem Status REJECTED abgelehnt.
20,00 EURBis zu diesem Betrag wird keine TAN Authentifizierung erwartet, bei genau 20 Euro wird die Auswahl der TAN-Verfahren noch zusätzlich ausgespielt (ohne dass eine TAN eingegeben werden muss)
20,02 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Photo-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 21,00€ verhalten. Bei Auswahl des TAN-Verfahrens wird dann festgelegt, dass keine TAN-Eingabe notwendig ist (EXEMPTED)
21,00 EURBei PSD2-Zahlung mit TAN Authentifizierung wird nur Photo-TAN Verfahren ausgespielt
21,01 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Photo-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 21,00€ verhalten.
22,00 EURBei PSD2-Zahlung mit TAN Authentifizierung wird nur Push-TAN Verfahren ausgespielt
22,01 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Push-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 22,00€ verhalten.
23,00 EURBei PSD2-Zahlung mit TAN Authentifizierung wird nur Flicker-TAN Verfahren ausgespielt
23,01 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Flicker-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 23,00€ verhalten.
23,45 EURBei PSD2-Zahlung mit TAN Authentifizierung wird keine automatische Status-Änderung für Push-, Photo- und Flicker-TAN passieren. Der SCA-Status und der Transaktion-Status müssen im testportal per paymentId manuell gesetzt werden.
403,01 EURSimuliert beim Start einer PSD2-TAN-Authentifizierung bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort.
403,03 EURSimuliert bei einer PSD2-Statusabfrage bei einer Volksbank eine 403 (forbidden) mit dem Grund EXPIRED als Antwort.
403,04 EURSimuliert beim Abschicken einer PSD2-TAN bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort.
403,05 EURSimuliert bei Auswahl einer PSD2-TAN-Authentifizierungsmethode bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort.
403,13 EURSimuliert bei einer PSD2-Statusabfrage bei einer Volksbank eine 403 (forbidden) mit dem Grund BLOCKED als Antwort.
405,02 EURSimuliert bei einer PSD2-Löschung eine 405 (method not allowed) als Antwort.
408,04 EURSimuliert bei einer PSD2-TAN-Authentifizierung eine lange Antwortzeit (für einen Timeout).
422,00 EURSimuliert bei einer PSD2-Zahlung eine 422 (not processable) als Antwort.
422,01 EURSimuliert bei einer PSD2-Authentifizierung eine 422 (not processable) als Antwort.
503,00 EURSimuliert bei einer PSD2-Zahlung eine 503 (not available) als Antwort.
503,01 EURSimuliert bei einer PSD2-Authentifizierung eine 503 (not available) als Antwort.

Transaktionstypen

Detaillierte Informationen zu den Transaktionstypen.

SALEAUTHREFUNDCAPTUREREFUND

Workflow

Käufer/KundeShopGiroCheckoutgiropayOnline-Banking1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 (c)2022 by GiroSolution AG

  1. Käufer/Kunde wählt giropay
  2. Shop initiiert giropay Transaktion (Initialisierung)
  3. GiroCheckout initialisiert Transaktion bei giropay
  4. giropay übermittelt Ergebnis an GiroCheckout
  5. Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)
  6. Shop sendet Redirect URL an Käufer-/Kundenbrowser
  7. Käufer-/Kundenbrowser leitet zu giropay weiter, wo die Bankauswahl erfolgt (optional, falls nicht schon im Browser gespeichert)
  8. giropay leitet dann an das Online-Banking der entsprechenden Bank weiter
  9. Online-Banking zeigt Loginseite an
  10. Käufer/Kunde autorisiert Transaktion
  11. Bank führt Auftrag durch
  12. Bank übermittelt Ergebnis an giropay
  13. giropay übermittelt Ergebnis an GiroCheckout
  14. GiroCheckout benachrichtigt Shop über Ausgang (Benachrichtigung)
  15. Shop verarbeitet Ausgang
  16. Shop sendet HTTP Statuscode an GiroCheckout
  17. GiroCheckout sendet Rücksprung zum Händler an giropay
  18. Käufer/Kunde klickt „Zurück zum Shop“ (Rücksprung)

Reservieren (AUTH)

Eine Reservierung ist zu verwenden, wenn die Erfüllung eines Auftrages zu einem späteren Zeitpunkt erfolgt, zum Zeitpunkt der Bestellung aber der Bestellwert für die vom Kunden vorgelegte Karte genehmigt werden soll (bei Kreditkarten-Transaktionen) bzw. die angegebene Bankverbindung geprüft werden soll (z.B. bei Paydirekt). Nach Ablauf dieses Zeitraumes wird die Reservierung entweder gebucht oder storniert.

  • initiale Transaktion

AUTHcapturerefund

Reservieren/Buchen (SALE)

Verkauf ist zu verwenden, wenn der Geschäftsvorgang abgeschlossen ist, also z. B. ein Warenkorb angeboten, bestellt und an den Kunden ausgeliefert wurde. Das Zahlungsmittel des Kunden wird in Höhe des Betrags belastet.

  • initiale Transaktion

SALErefund

API-Funktionen

Übersicht

Wie im Workflow dargestellt, gibt es mehrere API-Aufrufe während einer giropay Transaktion.

  1. Transaktion initiieren
  2. Bezahlinformation an Händler übermitteln
  3. Bezahlinformation mit Käuferbrowserweiterleitung zurück zum Händler (durch Käufer nach Zahlung ausgelöst oder automatisch nach einigen Sekunden)

Im Folgenden werden die API-Felder und Aufrufe näher erläutert.

Initialisierung einer giropay Zahlung

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, eine HTML-Seite mit entsprechendem Meta-Tag oder Javascript erfolgen.

Anfrage

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

POST 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. 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
currency Ja String(3) Währung der Transaktion
EUR = Euro
purpose Ja String(27) Verwendungszweck der giropay Überweisung. Zulässige Zeichen entsprechend dem SEPA-Zeichensatz (s. SEPA-konforme Zeichen).
type Optional String(4) Transaktionsart (siehe Transaktionsarten)
SALE = Verkauf wird sofort gebucht (default)
AUTH = Reservierung des Betrags
shoppingCartType Optional String(19) Typ des Warenkorbs. Folgende Werte sind zulässig:
PHYSICAL = Alle Waren im Warenkorb sind physischer Natur,
DIGITAL = Alle Waren im Warenkorb sind digitaler Natur (benötigen also keinen Versand),
MIXED = Der Warenkorb enthält sowohl physische als auch digitale Waren (dies ist der Default-Wert, wenn der Parameter nicht angegeben wird),
ANONYMOUS_DONATION = Es handelt sich um eine anonyme Spende (keine Adressdaten notwendig),
AUTHORITIES_PAYMENT = Es handelt sich um eine Behördenzahlung (keine Adressdaten notwendig)
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 (UTF-8, auch ausländisch), 0-9, die Zeichen .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[] , außerdem Leerzeichen und Zeilenumbruch.
shippingAddresseLastName (s. Beschr.) String(100) Nachname des Addressaten, Pflicht bei Warenkorbtypen PHYSICAL, DIGITAL und MIXED, optional bei ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen s. shippingAddresseLastName.
shippingCompany Optional String(100) Firmenname. Zulässige Zeichen s. shippingAddresseLastName.
shippingAdditionalAddressInformation Optional String(100) Addresszusatz. Zulässige Zeichen s. shippingAddresseLastName.
shippingStreet Optional String(100) Straße des Addressaten. Zulässige Zeichen s. shippingAddresseLastName.
shippingStreetNumber Optional String(10) Hausnummer des Addressaten. Zulässige Zeichen s. shippingAddresseLastName.
shippingZipCode (s. Beschr.) String(10) PLZ des Addressaten. Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen s. shippingAddresseLastName.
shippingCity (s. Beschr.) String(100) Ort des Addressaten. Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen s. shippingAddresseLastName.
shippingCountry (s. Beschr.) String(2) Ländercode (nach ISO 3166-1). Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT.
shippingEmail (s. Beschr.) String(255) Email-Adresse des Käufers. Pflicht bei digitalen Warenkörben (DIGITAL), bei allen anderen optional.
merchantOrderReferenceNumber Optional String(20) Zusatzinformation für die Zahlungszuordnung, die im Verwendungszweck angezeigt wird (nur bei type=SALE). Zulässige Zeichen entsprechend dem SEPA-Zeichensatz (s. SEPA-konforme Zeichen).
cart Optional JSON String alle Elemente des Warenkorbs im folgenden Format: s. weiter unten: Beschreibung cart-Element. Zulässige Zeichen s. shippingAddresseLastName.
deliveryType Optional String(12) Typ des Versands. Folgende Werte sind zulässig:
STANDARD = Die Ware wird an eine normale Postadresse versandt (dies ist der Default-Wert, wenn der Parameter nicht angegeben wird),
PACKSTATION = Die Waren werden an eine Selbstbedienungs-Packstation für Pakete geliefert,
STORE_PICKUP = Die Waren werden in der Geschäftsstelle des Verkäufers abhgeholt.
urlRedirect Ja String(2048) URL, an die der Kunde nach der Zahlung geschickt werden soll.
urlNotify Ja String(2048) URL, an die der Zahlungsausgang gemeldet werden soll.
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.
giropayCustomerId Optional String(20) Kundennummer, max. Länge: 20
hash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "shoppingCartType=DIGITAL" \
     -d "shippingAddresseFirstName=Max" \
     -d "shippingAddresseLastName=Mustermann" \
     -d "shippingEmail=mmuster@example.com" \
     -d "urlRedirect=http://www.ihre-domein.de/girocheckout/redirect" \
     -d "urlNotify=http://www.ihre-domein.de/girocheckout/notify" \
     -d "hash=2017e2f4d694e24a3396d83a20b3828b" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Antwort

Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Transaktion erfolgreich initialisiert. Es wird als Antwort eine Transaktionsnummer und die redirectURL zum Online Banking des Käufers zurückgeliefert.

Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Fehlernummer
msg Ja String(255) zusätzliche Informationen im Fehlerfall
reference Optional String(36) eindeutige GiroCheckout Transaktions-ID
redirect Optional String(2048) Redirect URL zur Weiterleitung des Kunden an sein Online Banking
HEADER Parameter
hash Ja String(32) HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort
Beispiel im Erfolgsfall

hash : f56b5f91094cd22ace93b76ef250aa62

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
Beispiel im Fehlerfall

hash : baf3c9b7217f362c29dd5cf6f098320c

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}

SEPA-konforme Zeichen

In SEPA-Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens nur Zeichen des eingeschränkten SWIFT Latin Character Set zugelassen:

  • a b c d e f g h i j k l m n o p q r s t u v w x y z
  • A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
  • 0 1 2 3 4 5 6 7 8 9
  • ' : ? , - ( + . ) /
  • Leerzeichen

cart-Element

JSON Array mit item Objekten

Name Pflicht Type Beschreibung
name Ja String(100) Artikelname
ean Optional String(100) Die Internationale Artikel Nummer (EAN bzw. GTIN)
quantity Ja Integer Menge des Artikels (Ganzzahl)
grossAmount Optional Integer Brutto- und Einzelbetrag des Artikels (also Preis pro Stück, bei mehreren), bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
Beispiel
[ {
    "name" : "Bobbycar",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helm",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]

Benachrichtigung über den Zahlungsausgang

Der Ausgang einer giropay-Zahlung wird an die im urlNotify-Parameter angegebene URL übermittelt. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden.

Der Zahlungausgang der giropay Transaktion steht im Feld gcResultPayment.

Am Ende des Bezahlvorganges auf giropay-Seite findet nach 5 Sekunden eine Weiterleitung an den Shop statt.

Anfrage

URL: notifyUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout

GET Parameter
Name Pflicht Type Beschreibung
gcReference Ja String(36) GiroCheckout Transaktions-ID
gcMerchantTxId Ja String(255) Händler Transaktions-ID
gcBackendTxId Ja String(36) Zahlungsabwickler Transaktions-ID
gcAmount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent
gcCurrency Ja String(3) Währung
gcResultPayment Ja Integer/String(1) String „0“ oder numerischer Ergebniscode der giropay Zahlung
gcHash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Antwort

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

HTTP Statuscode Beschreibung
200 (OK) Die Benachrichtigung wurde korrekt verarbeitet.
400 (Bad Request) Der Händler 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 Händler den HTTP Statuscode 200 oder 400 zurückgibt.

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 5 Sekunden erfolgt aber auch eine automatische Weiterleitung.

Anfrage

URL: redirectUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout

GET Parameter
Name Pflicht Type Beschreibung
giropaygiropay-IDgiropay+giropay-ID
gcReference Ja Ja Ja String(36) GiroCheckout Transaktions-ID
gcMerchantTxId Ja Ja Ja String(255) Händler Transaktions-ID
gcBackendTxId Ja Ja Ja String(36) Zahlungsabwickler Transaktions-ID
gcAmount Ja Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent
gcCurrency Ja Ja String(3) Währung
gcResultPayment Ja Ja Integer/String(1) String „0“ oder numerischer Ergebniscode der giropay Zahlung
gcHash Ja Ja Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe 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/giropay/senderinfo
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

POST-Parameter
Name Pflicht Type Beschreibung
merchantId Ja Integer Händler-ID eines giropay Projekts
projectId Ja Integer Projekt-ID eines giropay Projekts
reference Ja String(36)GiroCheckout Transaktions-ID
hash Ja String(32)HMAC MD5 hash über alle Werte des Aufrufs (siehe hash generieren)
Beispiel
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \
     -d "hash=246d1fa2ed97ecff895de974c560f9ec" \
     https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo

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 Fehlernummer
msg Ja String(255) zusätzliche Informationen im Fehlerfall
accountholder Optional String(255) Inhaber des Absenderkontos
iban Optional String(36) 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 hash der Rückantwort
Beispiel im Erfolgsfall

hash : cde71b6b98e8dae709fdc1e17aef885f

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
Beispiel im Fehlerfall

hash : f1d186103b8c4cb59c54ae7b987a9d4c

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}

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

ShopGiroCheckoutgiropay1 2 3 4 (c)2024 by S-Public Services GmbH

  1. Shop sendet referenzierende Transaktion
  2. GiroCheckout leitet Transaktion zu giropay
  3. giropay übermittelt Ergebnis an GiroCheckout
  4. Shop bekommt Rückmeldung über Transaktionsausgang (Benachrichtigung)

Buchen (CAPTURE)

Beim Buchen (capture) wird das Kundenkonto mit einem Betrag belastet, die Gutschrift erfolgt auf das Händlerkonto. Dieses Modell setzt voraus, dass der zugrundeliegende Geschäftsvorfall abgeschlossen ist, z.B. wurde ein Warenkorb angeboten, bestellt und an den Kunden ausgeliefert.

  • Bedingung: nur reservierte Transaktionen können gebucht werden
  • Betrag ⇐ Reservierungsbetrag
  • Buchung von Teilbeträgen möglich

AUTHauthCAPTURE

Erstattung (REFUND)

Eine Erstattung ist zu verwenden, wenn dem Kunden eine vorangegangene Zahlung komplett oder teilweise erstattet werden soll.

  • Bedingung: kann nur auf folgende Transaktionstypen angewendet werden:
    • Buchung (capture)
    • Reservierung + Buchung (sale)
  • Betrag ⇐ Transaktionsbetrag der vormals gesendeten Transaktion

SALEAUTHsaleREFUNDauthREFUND

POST Parameter

URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Name PflichtType Beschreibung
CAPTURE REFUND
merchantId Ja Ja Integer Händler-ID eines giropay-Projekts
projectId Ja Ja Integer Projekt-ID eines giropay-Projekts
merchantTxId Ja Ja String(255) Eindeutige Transaktions-ID des Händlers. Zulässige Zeichen: beliebige Buchstaben (inkl. sprachl. Sonderzeichen), 0-9, Zeichen & = + , : ; . _ ! ? # /
amount Ja Ja Integer Betrag oder Teilbetrag, zwischen 1 und 5000000 (also min. 1 Cent, max. 50000 EUR), bei Refund zwischen 1 und 10000000 (max. 100000 EUR). Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
currency Ja Ja String(3) Währung der Transaktion, gemäß ISO 4217.
EUR = Euro
purpose Ja Ja String(37) Verwendungszweck der Transaktion. Diese Information erscheint auf der Abrechnung.
reference Ja Ja String(36) GiroCheckout Transaktions-ID der zugrundeliegenden AUTH-Transaktion.
merchantReconciliationReferenceNumber Optional Optional String(30) Zusatzinformation für die Zahlungszuordnung, die im Verwendungszweck angezeigt wird.
final Optional Boolean NUR CAPTURE. Letzter CAPTURE auf eine Reservierung. Danach kann auf die referenzierte Reservierung kein weiterer CAPTURE mehr erstellt werden.
kassenzeichen Optional String(255) NUR CAPTURE. 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.
hash Ja Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=10000" \
     -d "currency=EUR" \
     -d "purpose=Beispiel-Capture" \
     -d "reference=dd724940-5e86-4072-8442-2c2ba2aebc79" \
     -d "final=true" \
     -d "hash=e4e57b71b094d7fa197374f4fbdd4ca9" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

Antwort

Die Antwort besteht aus einem JSON Objekt. Das Feld resultPayment liefert einen Fehlercode zurück. Wird resultPayment = 4000 zurückgeliefert, wurde die Transaktion erfolgreich durchgeführt. Sie bekommen als Antwort eine Transaktionsnummer zurück.

Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Antwortcode
msg Ja String(255) zusätzliche Informationen im Fehlerfall
reference Ja String(36) GiroCheckout Transaktions-ID
merchantTxId Ja String(255) Händler Transaktions-ID
backendTxId Ja String(36) Zahlungsabwickler Transaktions-ID
amount Ja Integer Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent
currency Ja String(3) Währung
resultPayment Ja Integer Ergebnis der Zahlung
hash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel im Erfolgsfall

hash : 36dc1f4622d0c1260fe5da76fe83fbd3

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
Beispiel im Fehlerfall

hash : c7dcb2d7d5e6719c6a51d81705bfc3af

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}

Stornierung (VOID)

Stornieren ist zu verwenden, wenn eine akzeptierte Transaktion nicht ausgeführt werden soll.

  • Bedingung: kann nur auf folgende Transaktionstypen angewendet werden:
    • Reservierung (solange keine Buchung erfolgte und Reservierung nicht abgelaufen ist)
    • Reservierung/Buchung (nur am selben Tag)
    • Erstattung (nur am selben Tag)

POST Parameter

URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

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. Zulässige Zeichen: beliebige Buchstaben (inkl. sprachl. Sonderzeichen), 0-9, Zeichen & = + , : ; . _ ! ? # /
reference Ja String(36) GiroCheckout Transaktions-ID, für die eine Stornierung durchgeführt werden soll
hash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Antwort

Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Transaktion erfolgreich initialisiert. Sie bekommen als Antwort eine Transaktionsnummer und weitere Informationen zurück.

Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Fehlernummer
msg Ja String(255) zusätzliche Informationen im Fehlerfall
reference Ja String(36) GiroCheckout Transaktions-ID
referenceParent Ja String(36) GiroCheckout Transaktions-ID der zugrundeliegenden Ursprungstransaktion
merchantTxId Ja String(255) Händler Transaktions-ID
backendTxId Ja String(36) Zahlungsabwickler Transaktions-ID
amount Ja Integer Stornierter Betrag, bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
currency Ja String(3) Währung
resultPayment Ja Integer Ergebnis der Transaktion
hash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel im Erfolgsfall
{"reference":"ef27303f-87b3-465e-9c39-fabfb749d253","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1226723_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
Beispiel im Fehlerfall
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}
girocheckout/giropay/start.txt · Zuletzt geändert: 2024/06/05 18:24

Seiten-Werkzeuge