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 customer 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 so that a URL to the payment page can be generated. This payment page URL is the result of a successful payment page initialization. The customer must be redirected to this URL afterwards.

Provided by: GiroCheckout
Called by: Merchant

Workflow

CustomerShopGiroCheckoutPayment PagePayment ProcessorCustomerShopGiroCheckoutPayment PagePayment Processor1 2 3 4 5 6 7 8 9 10 11 12 13 (c)2017 by GiroSolution AG

  1. Customer visits checkout section of the shop in order to pay for his order
  2. Shop initializes a paypage transaction (Initialization)
  3. GiroCheckout initializes transaction internally and returns paypage URL
  4. Shop redirects customer to the paypage, customer selects payment method
  5. Paypage initializes payment in GiroCheckout
  6. GiroCheckout returns URL of the payment form to the paypage
  7. Paypage redirects customer to the payment form of the payment processor, customer enters data and pays
  8. Payment processor informs GiroCheckout about transaction result
  9. GiroCheckout notifies shop about transaction result (Notification)
  10. Shop processes transaction result
  11. Shop sends HTTP status code to GiroCheckout
  12. GiroCheckout redirects customer back to the shop
  13. Shop displays result to customer

API functions

Initialization

POST Parameters

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

Name Mandatory Type Description
merchantId Yes Integer Merchant ID of a Paypage project
projectId Yes Integer Project ID of a Paypage project
merchantTxId Yes String(255) Eindeutige Transaktions-ID des Händlers
amount Yes Integer Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
currency Yes String(3) Währung der Transaktion, gemäß ISO 4217.
EUR = Euro
purpose Yes 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 Yes Integer 1 = Zahlarten im Test-Modus werden angezeigt
0 = Zahlarten im LIVE-Modus werden angezeigt
successUrl Yes String URL, an die der Kunde nach erfolgreicher Zahlung weitergeleitet wird.
backUrl Yes String URL, an die der Kunde weitergeleitet wird, wenn er auf Zurück klickt.
failUrl Yes 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 Yes 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"}

Notification about transaction result

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.1490020575.txt.gz · Last modified: 2021/04/12 14:33

Page Tools