User Tools

Site Tools

Translations of this page:

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


PlantUML Graph

  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


POST Parameters


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 Optional String URL where the customer is redirected to after successful payment.
backUrl Optional String URL where the customer is redirected to after clicking the Back button.
failUrl Optional 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 payments, according to Annex 3 of this document, only characters of the limited SWIFT Latin characters set are allowed:

  • 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

These are the allowed values for the payment methods specified in the parameter paymethods:

ID Payment method
1 giropay
2 eps
6 direct debit
7 direct debit with block file
8 direct debit with guarantee
11 credit card
12 iDEAL
14 PayPal
23 paydirekt
27 SOFORT Überweisung
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=" \
     -d "backUrl=" \
     -d "failUrl=" \
     -d "notifyUrl=" \
     -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \


The response consists of a JSON object. The field rc returns an error code. If rc = 0 is returned, the transaction was successfully initialized. As a response, you receive a reference number for the payment page and the redirect URL that leads to the form.

Name Mandatory Type Description
rc Yes Integer Error codes
msg Yes String Additional information in case of an error
reference Optional String Unique payment page ID
url Optional String URL to the payment page, that the customer is to be redirected to.
HEADER Parameters
hash Yes String HMAC MD5 hash of all values of the response. See hash on response
Example in case of success

hash : 6c4da0504e8e6a359c7f2df86cb5318d

Example in case of failure

hash : f55ce87e132ebb7eb20004c6b186ce09

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

Notification about transaction result

The result of a transaction is transmitted to the URL specified in the parameters successUrl or failUrl. This notification is used to inform the merchant about the result of the transaction, who can use this information to update his transaction status in the shop. The result of the transaction can be found in the field gcResultPayment.


URL: successUrl and failUrl from the payment page initialization
Provided by: Merchant
Called by: GiroCheckout Method: POST

Name Mandatory Type Description
gcPaymethod Yes Integer ID of the payment method of the transaction
gcType Yes String Transaction type:
gcProjectId Yes String GiroCheckout project ID used for the transaction.
gcReference Yes String GiroCheckout transaction ID
gcMerchantTxId Yes String Merchant transaction ID
gcBackendTxId Yes String Payment processor transaction ID
gcAmount Yes Integer For currencies with decimals, specify the amount in the smallest currency unit, such as Cent, Penny
gcCurrency Yes String Currency
gcResultPayment Yes Integer Payment result codes
gcPkn Optional String Pseudo card number if pkn is active
gcCardnumber Optional String Masked credit card number if pkn is active
gcCardExpDate Optional String Credit card expiration date in the format month/year if pkn is active
gcAccountHolder Optional String Account holder for direct debit if pkn is active
gcIban Optional String IBAN for direct debit if pkn is active
gcHash Yes String HMAC MD5 hash on all values of the call. See hash generation
en/girocheckout/paypage/start.txt · Last modified: 2017/07/21 15:47 by michaelheumann

Page Tools