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

Supported payment methods

The following payment methods are currently supported:

Payment method	Code
giropay	1
giropay-ID + giropay	17
giropay with payment confirmation	18
eps	2
iDEAL	12
Credit card	11
Direct debit	6
Direct debit with lock file	7
Guaranteed direct debit	8
Bluecode	26
Maestro	33
PayPal	14
paydirekt	23
SOFORT-Überweisung	27

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

Project request

In case you have the requirement of only offering in your payment or donation page payment methods associated to certain projects in your GiroCockpit, and letting someone choose these methods programmatically, you may use this request to obtain a list of all your projects.

URL: https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
Provided by: GiroSolution
Called by: Merchant

POST Parameters

Name	Mandatory	Type	Description
merchantId	Yes	Integer	Merchant ID of a Paypage project
projectId	Yes	Integer	Project ID of a Paypage project
hash	Yes	String	HMAC MD5 hash of all the parameter values in the call. See hash generation

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \
     https://payment.girosolution.de/girocheckout/api/v2/paypage/projects

Response

The response consists of a JSON object. The field rc returns an error code. If rc = 0 is returned, the call was successful. In the response, you receive the element “projects” that contains the available projects.

Parameters

Name	Mandatory	Type	Description
rc	Yes	Integer	Error codes
msg	Yes	String	Additional information in case of an error
projects	Optional	Array	List of the GiroCockpit projects with the elements Project Id (id), Projekt name (name), the number of the corresponding payment method (paymethod, see List of payment methods) and the mode (mode) = TEST or LIVE.
HEADER Parameters
hash	Yes	String	HMAC MD5 hash of all values of the response. See hash on response

Example

{"projects":[{"id":"12345","name":"iDEAL - ICEPAY","paymethod":"12","mode":"LIVE"},{"id":"12346","name":"giropay","paymethod":"1","mode":"TEST"},{"id":"12347","name":"Kreditkarte","paymethod":"11","mode":"TEST"}],"rc":0,"msg":""}

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. This parameter is MANDATORY, except for donation pages with free amount entry or with at least one fixed amount (meaning it is optional if pagetype == 2 and (freeamount=1 or fixedvalues not empty)).
currency	Yes	String(3)	Currency of the transaction, according to ISO 4217. EUR = Euro
purpose	Yes	String(27)	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). If pagetype=2 and projectlist is not empty, the placeholder {SPENDENPROJEKT} may be used, which is then filled with the name of the user-selected project. The content of this field (first 20 characters) is also used to fill the orderid in case of the payment method Paydirekt, if it is not explicitly specified (see parameter orderid).
description	Optional	String(120)	Description for the payment. Is only displayed on the payment page. Allowed characters see Allowed description characters
pagetype	Optional	Integer	Type of the payment page to be generated: 0=normal API-Paypage (compatible to previous paymnent pages, default), 1=Payment page, 2=Donation page
expirydate	Optional	String(10)	Expiration date: Empty=payment page is always valid, YYYY-MM-DD=Date in format Year-Month-Day, payment page will be valid up to this date. The option 'once' is deprecated and shouldn't be used anymore because it will not be available in a future API version. Please use single=2 instead.
single	Optional	Integer	Controls, whether and how the link may be reused. 0 = Link may be used as often as needed (default) 1 = Allows only one payment attempt for this payment link, no matter if successful or not 2 = Payment page may only be used for one successful payment, afterwards it will be invalidated
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
payprojects	Optional	String	Comma-separated list of the project IDs, whose payment methods are to be available on the payment page. If nothing is specified here, all projects of the merchant are used. The project IDs may either be obtained manually through GiroCockpit, or programatically via a call to the function Project Request.
organization	Optional	String(70)	Name of the organization offering the payment or donation page. If none specified, the merchant name from GiroCockpit is used.
freeamount	Optional	Integer	Defines whether the payment page user may freely enter an amount (=1) or not (=0, default).
fixedvalues	Optional	String	JSON-encoded string that contains an array of all the amounts among which the user may select the one to be paid/donated, e.g. '[“10000”,“20000”,“50050”]', all amounts are to be specified in cents. If this field is empty, the content of the amount field is used as a only possible value. If this field contains values, the amount field is ignored!
minamount	Optional	Integer	Minimum accepted value if free amount entry is allowed, i.e. freeamount=1. If this value is omitted, the default is 100 (meaning 1,00). Amount specified in cents.
maxamount	Optional	Integer	Maximum accepted value if free amount entry is allowed, i.e. freeamount=1.
orderid	Optional	String(20)	Only used when payment method is Paydirekt. If empty, the orderid is generated from the purpose field. Only sepa-compliant characters are allowed (see SEPA-compliant characters)
projectlist	Optional	String	JSON-encoded string, that contains an array of projects (strings=project names), for which the donation page accepts donations. Only makes sense if pagetype=2.
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
certdata	Optional	Integer	1 = Offer form for entering donation certificate data 0 = Do not offer the form (default)
otherpayments	Optional	String	JSON-formatted array of objects, that allows for the integration of external payment methods into the payment page. Clicking on this payment method within the payment page, will redirect to the specified link directly, instead of being processed via the GiroCheckout gateway as in the case of the rest of the methods. Currently, only payment methods listed in the list of already supported payment methods are allowed here (see Payment methods). Fields of the objects: id: Number of the payment method according to the list mentioned above. url: Link to which the browser will be redirected on click. This link must contain everything that is required on behalf of the external payment provider (such as PayPal), so that the payment can be processed. The payment page does not carry out any string replacements or so. position: Position that the new payment method will have within the full list of available payment methods on the page (>=1) Example (PayPal and credit card): [{"id":14, "url": "https://www.paypal.de/process/123456&param1=48399", "position":1}, {"id":11, "url":"https://www.visa.com/whatever", "position":2}]
paydirektShippingFirstName	Optional	String(100)	First name for shipping address (only paydirekt PHYSICAL orders)
paydirektShippingLastName	Optional	String(100)	Last name for shipping address (only paydirekt PHYSICAL orders)
paydirektShippingZipCode	Optional	String(10)	Zip code for shipping address (only paydirekt PHYSICAL orders)
paydirektShippingCity	Optional	String(100)	City for shipping address (only paydirekt PHYSICAL orders)
paydirektShippingCountry	Optional	String(2)	Country code (ISO 2 chars) for shipping address (only paydirekt PHYSICAL orders)
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

Example

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

Response

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.

Parameters

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

{"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":""}

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 on 2 parallel paths. The notification and the redirect.

Notification

The first communication path is a host to host message sent to the URL specified in the parameter notifyUrl. This notification is used to inform the merchant about the result of the transaction, even if the buyer does not return to the shop page. This information can and should be used to update the transaction status in the shop. The result of the transaction can be found in the field gcResultPayment.

Request

URL: notifyUrl from the payment page initialization
Provided by: Merchant
Called by: GiroCheckout
Method: GET

Name	Mandatory	Type	Description
gcPaymethod	Yes	Integer	ID of the payment method of the transaction
gcType	Yes	String	Transaction type: SALE AUTH
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

Redirect

The second communication path is the redirection of the buyer within his/her browser to one of the three redirection URLs specified during initialization:

successUrl: Is redirected to after successful payments.
failUrl: Is redirected to when the payment was not successful or the customer clicked the cancel button on the page of the payment provider (bank, credit card processor etc.).
backUrl: Is redirected to when the buyer has chosen not to go through with the payment and has clicked the back button on the payment page (please don't confuse this button with the cancel button of the payment method in the form displayed AFTER payment method selection, because that cancellation would then be a transaction abort that will be redirected to the failUrl).

The success and fail URL are called via the POST method and obtain the same parameters specified for the notification above. In case of the backUrl no payment method has been chosen yet and no transaction has been initialized, so in case of this URL it is only a regular browser redirect without further parameters.

Girocheckout API

Sidebar

Integration

SDK

Others

Table of Contents

Payment Page

Supported payment methods

Payment initialization through the payment page

Workflow

API functions

Project request

POST Parameters

Example

Response

Parameters

Example

Initialization

POST Parameters

SEPA compliant characters

Allowed description characters

Example

Response

Parameters

Example in case of success

Example in case of failure

Notification about transaction result

Notification

Request

Redirect

Girocheckout API

User Tools

Site Tools

Sidebar

Integration

SDK

Others

Table of Contents

Payment Page

Supported payment methods

Payment initialization through the payment page

Workflow

API functions

Project request

POST Parameters

Example

Response

Parameters

Example

Initialization

POST Parameters

SEPA compliant characters

Allowed description characters

Example

Response

Parameters

Example in case of success

Example in case of failure

Notification about transaction result

Notification

Request

Redirect

Page Tools