Girocheckout API

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Zuletzt angesehen: • Payment Page

Seitenleiste

Einführung

Integration

Grundlagen
FAQ

Apple Pay
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Kreditkarte
Lastschrift
Maestro
Payment Page
PayPal

Tools

Fehlernummern
Ergebniscode
Testdaten

Erweiterungen

UATP
Vertriebspartner
Risikoprüfung
Formularservice

SDK

PHP SDK
Java SDK
.NET SDK

Andere

API Changelog
Plugins Changelog

Impressum
Datenschutz
S-Public Services GmbH

Übersetzungen dieser Seite:
girocheckout:paypage:start

Dies ist eine alte Version des Dokuments!

Inhaltsverzeichnis

Payment Page

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

Beispiel Payment Page

Es werden die folgenden Zahlarten unterstützt:

  • giropay
  • eps
  • iDEAL
  • Kreditkarte
  • Lastschrift
  • Lastschrift mit Sperrdatei
  • Garantierte Lastschrift
  • PayPal
  • paydirekt
  • SOFORT Überweisung

Initialisierung einer Zahlung über die Payment Page

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

Workflow

KundeShopGiroCheckoutPayment PageZahlungsabwicklerKundeShopGiroCheckoutPayment PageZahlungsabwickler1 2 3 4 5 6 7 8 9 10 11 12 13 (c)2017 by GiroSolution AG

  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

API-Funktionen

Initialisierung

POST Parameter

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

Name Pflicht Type Beschreibung
merchantId Ja Integer Händler-ID eines Maestro-Projekts
projectId Ja Integer Projekt-ID eines Maestro-Projekts
merchantTxId Ja String(255) Eindeutige Transaktions-ID des Händlers
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, gemäß ISO 4217.
EUR = Euro
purpose Ja String(20) Verwendungszweck der Transaktion. Diese Information erscheint auf der Kartenabrechnung bzw. dem Kontoauszug. Es sind nur SEPA-konforme Zeichen zulässig (s. SEPA-konforme Zeichen)
description Optional String(40) Beschreibung für die Bezahlung. Wird nur auf der Payment Page angezeigt.
type Optional String(4) Transaktionsart (siehe Transaktionsarten)
SALE = Verkauf wird sofort gebucht (default)
AUTH = Reservierung des Betrags (nicht bei allen Zahlarten verfügbar)
locale Optional String(4) Sprache der Payment Page
de = deutsch (default)
en = englisch
paymethods Optional String Kommaseparierte Liste der Zahlarten, die angezeigt werden sollen. Wird hier nichts angegeben, werden alle beim Händler unterstützen Zahlarten zur Auswahl angeboten. Jede Zahlungsart ist als Zahl anzugeben, s. Zahlungsarten
pkn Optional String Das Feld dient dazu eine erneute Transaktion, ohne erneute Eingabe der Kreditkarten- oder Lastschriftdaten, zu starten.
create = neue Pseudo-Kartennummer für die verwendete Kreditkarte/Kontoverbindung generieren.
test Ja Integer 1 = Zahlarten im Test-Modus werden angezeigt
0 = Zahlarten im LIVE-Modus werden angezeigt
successUrl Ja String URL, an die der Kunde nach erfolgreicher Zahlung weitergeleitet wird.
backUrl Ja String URL, an die der Kunde weitergeleitet wird, wenn er auf Zurück klickt.
failUrl Ja String URL, an die der Kunde nach erfolgloser Zahlung weitergeleitet wird.
notifyUrl Optional String URL, an die in einer Server-to-Server-Verbindung die Payment Notification geschickt wird.
hash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

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
  • ' : ? , - ( + . ) /

Zahlungsarten

Dies sind die zulässigen Werten für die im Parameter paymethods anzugebenden Zahlungsarten:

ID Zahlungsart
1 giropay
2 eps
6 Lastschrift
7 Lastschrift mit Sperrdatei
8 Garantierte Lastschrift
11 Kreditkarte
12 iDEAL
14 PayPal
23 paydirekt
27 SOFORT Überweisung
Beispiel
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "description=Fahrradleuchte klein" \
     -d "type=SALE" \
     -d "locale=de" \
     -d "paymethods=1,2,6,11,14" \
     -d "test=1" \
     -d "successUrl=http://www.my-domain.de/girocheckout/success" \
     -d "backUrl=http://www.my-domain.de/girocheckout/back" \
     -d "failUrl=http://www.my-domain.de/girocheckout/fail" \
     -d "notifyUrl=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \
     https://payment.girosolution.de/girocheckout/api/v2/paypage/init

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

Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Fehlernummer
msg Ja String zusätzliche Informationen im Fehlerfall
reference Optional String eindeutige Payment Page ID
redirect Optional String URL zur Payment Page, an die der Kunde weitergeleitet werden muss.
HEADER Parameter
hash Ja String HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort
Beispiel im Erfolgsfall

hash : 6c4da0504e8e6a359c7f2df86cb5318d 

{"reference":"4f88b6c8-6209-4c96-a450-b6de22633f6b","url":"http:\/\/pay.girosolution.de\/v1\/paypage\/en\/EG-ddvXSrAHmXRClBeamKGAyzXU-uAYbNYFLQ3uz_zj_J4rYCb0GIrWIQ-H_g8h3_-yf3WvSenh2Dg6TLhmTAA","rc":0,"msg":""}
Beispiel im Fehlerfall

hash : f55ce87e132ebb7eb20004c6b186ce09 

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

Benachrichtigung über den Zahlungsausgang

Der Ausgang einer Zahlung wird an die im Parameter urlNotify 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 Zahlungsausgang einer Transaktion steht im Feld gcResultPayment.

Anfrage

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

GET Parameter

Name Pflicht Type Beschreibung
gcReference Ja String GiroCheckout Transaktions-ID
gcMerchantTxId Ja String Händler Transaktions-ID
gcBackendTxId Ja String Zahlungsabwickler Transaktions-ID
gcAmount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
gcCurrency Ja String Währung
gcResultPayment Ja Integer Ergebniscodes der Zahlung
gcHash Ja String 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 Zahlung kann der Kunde über einen Link zurück zum Händler kommen. Eine Weiterleitung erfolgt erst, wenn der Käufer den „Abbrechen“ oder „Zurück zum Shop“ Button drückt. Diese Rückleitung erfolgt nicht automatisch.

Anfrage

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

GET Parameter
Name Pflicht Type Beschreibung
gcReference Ja String GiroCheckout Transaktions-ID
gcMerchantTxId Ja String Händler Transaktions-ID
gcBackendTxId Ja String Zahlungsabwickler Transaktions-ID
gcAmount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
gcCurrency Ja String Währung
gcResultPayment Ja Integer Ergebnis der Zahlung
gcHash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Weitere Transaktionsarten

Diese Transaktionen 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

ShopGiroCheckoutKartenabwicklerShopGiroCheckoutKartenabwickler1 2 3 4 (c)2017 by GiroSolution AG

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

Buchung (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

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

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 Pflicht Type Beschreibung
merchantId Ja Integer Händler-ID eines Maestro-Projekts
projectId Ja Integer Projekt-ID eines Maestro-Projekts
merchantTxId Ja String(255) eindeutige Transaktions-ID des Händlers
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, gemäß ISO 4217.
EUR = Euro
reference Ja String GiroCheckout Transaktions-ID, für die eine Buchung oder Erstattung durchgeführt werden soll
hash Ja String 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 "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

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 zusätzliche Informationen im Fehlerfall
reference Ja String GiroCheckout Transaktions-ID
merchantTxId Ja String Händler Transaktions-ID
backendTxId Ja String Zahlungsabwickler Transaktions-ID
amount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
currency Ja String Währung
resultPayment Ja Integer Ergebnis der Transaktion
hash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel im Erfolgsfall

hash : eded41a45961bf87b77a5aaf3e9aeb0e 

{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}
Beispiel im Fehlerfall

hash : f55ce87e132ebb7eb20004c6b186ce09 

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}
girocheckout/paypage/start.1486670585.txt.gz · Zuletzt geändert: 2021/04/12 14:30

Seiten-Werkzeuge