User Tools

Site Tools


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

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

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) 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
en/girocheckout/paypage/start.1490022288.txt.gz · Last modified: 2021/04/12 14:33

Page Tools