This is an old revision of the document!

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

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

SVG | PNG | TXT

Customer visits checkout section of the shop in order to pay for his order
Shop initializes a paypage transaction (Initialization)
GiroCheckout initializes transaction internally and returns paypage URL
Shop redirects customer to the paypage, customer selects payment method
Paypage initializes payment in GiroCheckout
GiroCheckout returns URL of the payment form to the paypage
Paypage redirects customer to the payment form of the payment processor, customer enters data and pays
Payment processor informs GiroCheckout about transaction result
GiroCheckout notifies shop about transaction result (Notification)
Shop processes transaction result
Shop sends HTTP status code to GiroCheckout
GiroCheckout redirects customer back to the shop
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)	Merchant's unique transaction ID
amount	Yes	Integer	For currencies with decimals, specify the amount in the smallest currency unit, such as Cent, Penny
currency	Yes	String(3)	Currency of the transaction, according to ISO 4217. EUR = Euro
purpose	Yes	String(20)	Purpose of the transaction. This information is displayed on the card settlement or bank statement. Only SEPA compliant characters are allowed (see SEPA compliant characters)
description	Optional	String(120)	Description for the payment. Is only displayed on the payment page. Allowed characters see Allowed description characters
type	Optional	String(4)	Transaction type (see Transaction types) SALE = Immediate payment (default) AUTH = Amount reservation (not available for all payment methods)
locale	Optional	String(4)	Language of the payment page de = German (default) en = English
paymethods	Optional	String	Comma-separated list of the payment methods to be offered. If parameter is empty or not specified, all methods enabled by the merchant in GiroCockpit will be displayed. Specify each payment method as a number, see Payment methods
pkn	Optional	String	This field allows the initialization of a new transaction without having to input the credit card or direct debit data again (recurring payments). create = generate new pseudo card number for the payment data (credit card or bank data) used in this transaction.
test	Yes	Integer	1 = Display payment methods that are in test mode 0 = Display payment methods that are in Live mode
successUrl	Yes	String	URL where the customer is redirected to after successful payment.
backUrl	Yes	String	URL where the customer is redirected to after clicking the Back button.
failUrl	Yes	String	URL where the customer is redirected to after a failed payment.
notifyUrl	Optional	String	URL where the payment notification is sent to via server to server communication.
hash	Yes	String	HMAC MD5 hash of all the parameter values in the call. See hash generation

SEPA compliant characters

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

Allowed description characters

The following characters are allowed in the description text (field description):

All characrters of all languages, including German umlauts, Spanisch accented characters and so on.
All punctuation characters
All numerical digits
Symbols referring to currencies (e.g. $ and € etc.)
Length between 1 and 60 characters

Payment methods

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

Girocheckout API

Sidebar

Integration

SDK

Others

Table of Contents

Payment Page

Payment initialization through the payment page

Workflow

API functions

Initialization

POST Parameters

SEPA compliant characters

Allowed description characters

Payment methods

Beispiel

Antwort

Parameter

Beispiel im Erfolgsfall

Beispiel im Fehlerfall

Notification about transaction result

Anfrage

Girocheckout API

User Tools

Site Tools

Sidebar

Integration

SDK

Others

Table of Contents

Payment Page

Payment initialization through the payment page

Workflow

API functions

Initialization

POST Parameters

SEPA compliant characters

Allowed description characters

Payment methods

Beispiel

Antwort

Parameter

Beispiel im Erfolgsfall

Beispiel im Fehlerfall

Notification about transaction result

Anfrage

Page Tools