Girocheckout API

User Tools

Site Tools

Trace: • Payment Page

Sidebar

Introduction

Integration

Basics

Apple Pay
Bluecode
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal

Tools

Error codes
Result codes
Test data

SDK

PHP SDK
Java SDK
.NET SDK

Others

API Change log
Plugins Changelog

Imprint
Privacy policy
S-Public Services GmbH

Translations of this page:
en:girocheckout:paypage:start

This is an old revision of the document!

Table of Contents

Payment Page

This document describes all flows and interfaces that are required for an integration of the GiroCheckout Payment Page.

This payment page allows for a much simpler integration of shops with GiroCheckout, without the need to configure each payment method separately within the shop. The GiroCheckout Payment Page offers the buyer all payment methods available to the merchant for selection and then initializes the selected payment accordingly.

Example

Example Payment Page

The following payment methods are currently supported:

  • giropay
  • eps
  • iDEAL
  • credit card
  • direct debit
  • direct debit with block file
  • direct debit with guarantee
  • PayPal
  • paydirekt
  • SOFORT Überweisung

Payment initialization through the payment page

A payment page needs to be initialized 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(120) Beschreibung für die Bezahlung. Wird nur auf der Payment Page angezeigt. Zulässige Zeichen s. Zulässige Beschreibungszeichen
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
  • ' : ? , - ( + . ) /

Zulässige Beschreibungszeichen

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

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 Transaktionsausgang

Der Ausgang einer Transaktion wird an die im successUrl- oder failUrl-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 Zahlungsausgang einer Transaktion steht im Feld gcResultPayment.

Anfrage

URL: successUrl und failUrl aus der Payment-Page-Initialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout Methode: POST

Name Pflicht Typ Beschreibung
gcPaymethod Ja Integer ID der Zahlungsart der Transaktion
gcType Ja String Transaktionsart:
SALE
AUTH
gcProjectId Ja String GiroCheckout Projekt-Id, über die die Transaktion abgewickelt wurde.
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
gcPkn Optional String Pseudokartennummer, wenn pkn aktiv
gcCardnumber Optional String Maskierte Kreditkartennummer, wenn pkn aktiv
gcCardExpDate Optional String Gültigkeitsdatum der Kreditkarte im Format Monat/Jahr, wenn pkn aktiv
gcAccountHolder Optional String Kontoinhaber bei Lastschrift, wenn pkn aktiv
gcIban Optional String IBAN bei Lastschrift, wenn pkn aktiv
gcHash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
en/girocheckout/paypage/start.1490014811.txt.gz · Last modified: 2021/04/12 14:33

Page Tools