In diesem Dokument werden alle Abläufe und Schnittstellen beschrieben, die zur Integration der GiroCheckout Payment Page notwendig sind.

Diese Payment Page ermöglicht eine viel einfachere Anbindung von Shops an GiroCheckout, ohne dass innerhalb des Shops alle Zahlungsarten einzeln konfiguriert werden müssen. Die GiroCheckout Payment Page bietet dem Endkunden alle beim Händler verfügbaren Zahlungsarten zur Auswahl an und initialisiert die entsprechende Zahlung nach Auswahl.

Beispiel

Seit dem 01.01.2021 ist das neue Sicherheitsverfahren für Kreditkartenzahlungen „3D Secure 2.0“, das im Zuge von PSD2 eingeführt wird, für alle Zahlungsanbieter Pflicht. Die vorliegende API-Beschreibung enthält alle hierfür notwendigen Felder (beginnend mit „tds2“), s. Transaktionsinitialisierung weiter unten.

Beachten Sie: Die Parameter bzgl. 3-D Secure 2.0 können sich aufgrund von Änderungen der EMVCo 3-D Secure-Spezifikation ändern.

Es werden die folgenden Zahlarten unterstützt:

Eine Payment Page muss initialisiert werden, damit eine Payment-Page-URL generiert wird. Diese Payment-Page-URL ist das Ergebnis einer erfolgreichen Payment-Page-Initialisierung. Der Endkunde muss anschließend auf diese URL weitergeleitet werden.

Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

1. Käufer besucht Shop-Checkout um zu bezahlen
2. Shop initialisiert Paypage-Transaktion (Initialisierung)
3. GiroCheckout initialisiert Transaktion intern und liefert Paypage-URL zurück
4. Shop leitet Kunden zur Paypage weiter, Kunde wählt Zahlungsart
5. Paypage initialisiert Zahlung bei GiroCheckout
6. GiroCheckout liefert URL des Zahlungsformulars an Paypage
7. Paypage leitet Kunden auf Zahlungsformular beim Abwickler weiter, Kunde gibt Daten ein und bezahlt
8. Zahlungsabwickler informiert GiroCheckout über Transaktionsausgang
9. GiroCheckout benachrichtigt Shop über Transaktionsausgang (Benachrichtigung)
10. Shop verarbeitet Transaktionsausgang
11. Shop sendet HTTP Statuscode an GiroCheckout
12. GiroCheckout leitet Käufer zurück auf den Shop
13. Shop zeigt Kunde Ergebnis an

Sollte bei Ihnen der Bedarf bestehen, in Ihrer Payment- oder Spenden-Page nur bestimmte Projekte aus Ihrem GiroCockpit zu verwenden und dies in Ihrer Implementierung auswählen zu lassen, können Sie diese Abfrage verwenden, um sich Ihre Projekte zurückliefern zu lassen.

URL: https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
Bereitzustellen von: S-Public Services GmbH
Aufzurufen von: Händler

Die Antwort enthält ein JSON Objekt. Wenn rc = 0 zurückgeliefert wird, enthält das Element projects die zur Verfügung stehenden Projekte.

URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init

  Ziffern: 0 – 9  
  Buchstaben: A – Z und a – z  
  Sonderzeichen: ' : \ , ? - + . ( ) /

  Ziffern: 0 – 9  
  Buchstaben: A – Z und a – z  
  Sonderzeichen: & / = + , : ; . _ - ! ? 

Folgende Zeichen sind für den Beschreibungstext (Feld description) zulässig:

• Alle Buchstaben aller Sprachen, also auch Umlaute und spanische Sonderzeichen usw.
• Alle Satzzeichen
• Alle Ziffern
• Symbole, die sich auf Währungen beziehen (also $ und € usw.)
• Länge zwischen 1 und 60 Zeichen

Hierbei handelt es sich um ein JSON-formatiertes Objekt, das hierarchisch aufgebaut ist (2 Ebenen) und die folgenden Unterobjekte enthält:

• billingAddress (Rechnungsadresse)
• shippingddress (Lieferadresse)
• homePhoneNumber (Telefon zuhause)
• mobilePhoneNumber (Telefon mobil)
• workPhoneNumber (Telefon Arbeit)
• cardholderAccountInfo (Konteninformationen Karteninhaber)
• tdsMerchantRiskIndicators (Risikoindikatoren des Händlers)
• tdsRequestorAuthenticationInformation (Authentifizierungsinformationen des Anfragenden)
• tdsTransactionAttributes (Transaktionsattribute)

Insgesamt gibt es folgende Feldern (alle optional, Felder in Unterobjekten sind mit [Unterobjektname].[Feld] dargestellt):

{
  "email": "myemail@example.com",
  "addressesMatch": "false",
  "billingAddress": {
    "line2": "Beim Nachbarn klingeln",
    "line3": "zw. 22-24 Uhr",
    "state": "BW"
  },
  "shippingAddress": {
    "city": "Berlin",
    "country": "DE",
    "line1": "Unter den Linden 1",
    "line2": "Brandenburger Tor",
    "line3": "(linker Bogen)",
    "state": "BER"
  },
  "homePhoneNumber": {
    "country": "49",
    "regional": "75519209309"
  },
  "mobilePhoneNumber": {
    "country": "49",
    "regional": "17093902978"
  },
  "workPhoneNumber": {
    "country": "49",
    "regional": "8938928938"
  },
  "cardholderAccountInfo": {
    "accountAgeIndicator": "more30less60",
    "passwordChangeIndicator": "never",
    "paymentAccountAgeIndicator": "less30",
    "accountChange": "now",
    "shippingAddressAgeIndicator": "more60",
    "shippingNameIndicator": "different",
    "suspiciousAccountActivity": "false",
    "provisioningDayCount": 10
  },
  "tdsMerchantRiskIndicators": {
    "deliveryTimeframe": "overnight",
    "deliveryEmailAddress": "hans-mueller@example.com",
    "giftCardAmount": 0,
    "giftCardCount": 2,
    "giftCardCurrency": "EUR",
    "preOrderDate": "2020-12-20",
    "preOrderPurchaseIndicator": "available",
    "reorderItemsIndicator": "first",
    "shippingIndicator": "store"
  },
  "tdsRequestorAuthenticationInformation": {
    "authenticationData": "123Hdajkd/dasjdkk",
    "authenticationTimestamp": "2020-11-09T12:09:09",
    "authenticationMethod": "ownCredentials"
  },
  "tdsTransactionAttributes": {
    "purchaseInstalmentData": 2,
    "recurringExpiry": "2020-11-30",
    "recurringFrequency": 1234,
    "type": "quasiCash"
  }
}

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 Referenznummer für die Payment Page und die redirectURL zum Formular zurück.

JSON Array mit item Objekten:

[ {
    "name" : "Bobbycar",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helm",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]

Der Ausgang einer Transaktion wird auf 2 parallelen Wegen übermittelt. Der Notification und dem Redirect.

Der erste Kommunikationsweg ist eine Host-to-Host-Meldung an die im notifyUrl-Parameter angegebene URL. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen, auch wenn der Käufer nicht mehr auf die Shopseite zurückkehrt. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden. Der Zahlungsausgang einer Transaktion steht im Feld gcResultPayment.

URL: notifyUrl aus der Payment-Page-Initialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout
Methode: GET

Der zweite Kommunikationsweg ist die Rückleitung des Käufers in seinem Browser auf eine der drei bei der Initialisierung angegebenen Weiterleitungsadressen:

• successUrl: Hierher wird weitergeleitet, wenn die Zahlung erfolgreich war.
• failUrl: Hierher wird weitergeleitet, wenn die Zahlung nicht erfolgreich war oder auf der Seite des Zahlungsanbieters (Bank, Kreditkartenbetreiber usw.) abgebrochen wurde.
• backUrl: Hierher wird weitergeleitet, wenn der Käufer auf der Payment Page beschließt, den Vorgang abzubrechen und auf den Zurück-Button klickt (nicht zu verwechseln mit dem Abbruch der Zahlung im entsprechenden Zahlungsformular NACH Auswahl der Zahlart, denn dieser Abbruch entspricht dann einem Transaktionsabbruch, der an die failUrl weitergeleitet wird).

Die success- und failUrl werden mit der POST-Methode aufgerufen und erhalten die selben Parameter wie oben beim Notify angegeben. Bei der backUrl wurde ja noch keine Zahlungsart ausgewählt und auch keine Transaktion initialisiert, somit wird hier lediglich ein Browser-Redirect ohne weitere Parameter durchgeführt.

Diese Transaktionen referenzieren auf eine zuvor erfolgte Transaktion. Die Transaktion basiert auf einer Server-zu-Server-Kommunikation und erfordert keine Kundenaktion (Eingabe von Daten). Im Falle der Payment Page beachte man hierbei, dass diese Transaktionsarten (Buchung und Erstattung) sich dann jeweils auf die zugrundeliegende vorher durchgeführte Transaktion beziehen und somit ist die Aktion nur erlaubt, wenn die entsprechende Zahlungsart dies unterstützt.

Beispiel:

Wird ein Payment-Link dazu verwendet, eine Rechnung zu bezahlen, und der Kunde wählt die Zahlungsart Kreditkarte aus, so kann hinterher mit der Referenznummer der Payment-Page-Transaktion diese Zahlung erstattet werden. Hat es sich um eine Reservierung (type=AUTH) gehandelt, ist dann über dieselbe Referenznummer die Buchung (capture) machbar. Hat der Kunde aber mit giropay bezahlt, wo es keine Reservierung und Erstattung gibt, werden Versuche dies durchzuführen mit einer Fehlermeldung abgewiesen.

Weiterhin ist zu beachten, dass je nachdem, wie eine Payment- oder Spendenseite initialisiert wurde (Stichwort: single-Parameter), auch mehr als eine Zahlung über denselben Link getätigt worden sein kann. In diesem Falle, also wenn es mehr als eine erfolgreiche Zahlung zur Referenznummer der Payment-Page-Transaktion gibt, muss der optionale Parameter 'txreference' angegeben werden, der dann die Referenznummer enthält, die die konkrete Zahlungstransaktion identifiziert (diese wird ja jeweils in Notification und Redirect im Parameter 'gcReference' bzw. 'reference' zurückgeliefert).

Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

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

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

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.