Direct Debit

A direct debit payment can only be processed in Euros.

Test data

Bank account	Bank code	Response code	Result type	Description
1234567890	12345678	4000	successful transaction	A successful payment will be created.
1212121211	12345679	4051	unsuccessful transaction	An unsuccessful payment will be created.

IBAN	Response code	Result type	Description
DE87123456781234567890	4000	Successful transaction	A successful payment will be created.
DE23690516200012345600	5027	Unsuccessful transaction	An unsuccessful transaction will be created.

Workflow

The direct debit payment can be processed in two ways:

If the bank account data is known (IBAN or bank account and bank code), a transaction can be processed directly.
Alternatively a payment page can be used.

Direct debit with payment page

SVG | PNG | TXT

Buyer chooses direct debit payment method
merchant initialises direct debit transaction (initialising direct debit transaction)
GiroCheckout initialises transaction at direct debit processor
direct debit processor submits response to GiroCheckout
merchant gets response about initialisation (if an issue occurs the transaction is finished)
merchant sends redirect URL to buyer
the buyer's browser redirects buyer to the payment form
direct debit processor shows payment form
buyer authorises payment
transaction is beeing processed
direct debit processor submits payment result to bank
GiroCheckout notifies merchant about the payment result (payment result norification)
merchant processes result
merchant sends HTTP statuscode to GiroCheckout
GiroCheckout sends merchants redirect page to bank
buyer clicks “back to the shop” and gets redirected to the merchant (buyer redirection)

Direct debit without payment page

SVG | PNG | TXT

buyer choses direct debit payment and fills in his IBAN
merchant subits direct debit payent to GiroCheckout (direct debit without payment page)
GiroCheckout submits direct debit payent to the bank
bank replies and submits payment result to GiroCheckout
GiroCheckout replies merchant
merchant informs buyer about the payment result

API functions

Overview

As shown in the workflow there are different API calls during a direct debit transaction with payment page.

Initialize transaction
Request account information from customer
Transmit payment information to merchant
Payment information and buyer redirection to the merchant (triggered by buyer after payment)

As shown in the workflow there is just one API call during a direct debit transaction without payment page.

Process transaction

Initialize direct debit payment with payment page

After a successful initialization you receive a reference number and an redirect link. The redirect link leads to the payment page. He has to be redirected. This can be achieved by a HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: merchant

POST parameters

Name	Mandatory	Type	Description
merchantId	yes	Integer	merchant ID
projectId	yes	integer	project ID
merchantTxId	yes	String(255)	unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount	yes	Integer	if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency	yes	String(3)	currency EUR = Euro
purpose	yes	String(50)	purpose
type	optional	String(4)	Transaction type (see Transaction types) SALE = Immediate sale (default) AUTH = Reservation of amount
locale	optional	String(4)	language of the payment page de = German (default) en = English es = Spanish fr = French it = Italian pt = Portuguese nl = Dutch cs = Czech sv = Swedish da = Danish pl = Polish spde = German donation spen = English donation de_DE_stadtn = German communes
mobile	optional	Boolean	optimized payment page for mobile devices 0 = no (default) 1 = yes
mandateReference	optional	String(35)	mandate reference if nothing is specified, a unique number is generated. The reply includes the mandate reference number. numbers: 0 – 9 characters: A – Z and a – z special characters: & \ / = + , : ; . _ \ - ! ?
mandateSignedOn	optional	String(10)	date (YYYY-MM-DD), when the SEPA mandate was placed. If no date is specified the current date will be used.
mandateReceiverName	optional	String(70)	name of the recipient. If nothing is specified companies name from the master data is used. numbers: 0 – 9 characters: A – Z and a – z special characters: & / = + , : ; . _ - ! ?
mandateSequence	optional	Integer	Sequence type of the SEPA direct debit. 1 = single payment (default) 2 = first payment of a sequence 3 = recurring payment 4 = last payment of a sequence
pkn	optional	String(50)	This field is used to initiate a new transaction without the need for repeating the banking data. create = generate new pseudo card number for the used banking data [Pseudo card number] = Card number of the banking data to be used (see pseudo card number) This feature requires a separate configuration involving a one-time setup fee.
urlRedirect	yes	String(2048)	URL, where the buyer has to be sent after payment
urlNotify	yes	String(2048)	URL, where the notification has to be sent after payment
kassenzeichen	optional	String(255)	Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there. Characters must comply with the UTF-8 character set.
hash	yes	String(32)	HMAC MD5 hash (see hash generation)

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=52dd237537dce" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Lastschrift Transaktion" \
     -d "mandateReference=12345abcde" \
     -d "mandateSignedOn=2014-01-01" \
     -d "mandateReceiverName=mein Shop" \
     -d "mandateSequence=1" \
     -d "urlRedirect=https://www.your-domain.de/girocheckout/redirect-directdebit" \
     -d "urlNotify=https://www.your-domain.de/girocheckout/notify-directdebit" \
     -d "hash=f7ee5f58036e459bf42002fa89279041" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Reply

The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initiated. The response also includes a transaction id and a redirect URL to the payment page.

Parameters

Name	Mandatory	Type	Description
rc	yes	Integer	response code
msg	yes	String(255)	additional information about the response code
reference	optional	String(36)	unique GiroCheckout transaction ID
mandateReference	optional	String(35)	mandate reference of the SEPA direct debit
redirect	optional	String(2048)	redirect URL to the payment page
HEADER parameter
hash	yes	String(32)	HMAC MD5 hash overall the JSON string. (see api call reply)

Example in case of success

{"mandateReference":"12345abcde","reference":"928f3815-7e66-4650-aab5-a0edf92d41e6","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=vjqRec7hizjYXLE1t9272wi96FXqHKQQw5XD7RwwyiFH","rc":"0","msg":""}

Example in case of error

hash : 0afc26687fa0dcb2440a19107c273a7d

{"mandateReference":null,"reference":null,"redirect":null,"rc":5010,"msg":"Sprache ungültig"}

Notification of the payment result

The result of an initialized transaction will be submitted to the prior in the urlNotify parameter specified URL. This notification should be used to update the payment status in the merchant's system. The result of the payment is contained in the field gcResultPayment.

Request

URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameters

Name	Mandatory	Type	Description
gcReference	yes	String(36)	unique GiroCheckout transaction ID
gcMerchantTxId	yes	String(255)	merchant transaction ID
gcBackendTxId	yes	String(22)	payment processor transaction ID
gcAmount	yes	Integer	if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny
gcCurrency	yes	String(3)	currency
gcResultPayment	yes	Integer	payment result codes
gcHash	yes	String(32)	HMAC MD5 hash (see hash generation)

Reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code	Description
200 (OK)	The notification was processed correctly.
400 (Bad Request)	The merchant did not process the notification and does not wish to be notified again.
all others	The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400.

Redirection of the customer to merchant

After completing the payment, the customer may return to the merchant through a link. This return is not done automatically.

Request

URL: redirectUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameters

Name	Mandatory	Type	Description
gcReference	yes	String(36)	unique GiroCheckout transaction ID
gcMerchantTxId	yes	String(255)	merchant transaction ID
gcBackendTxId	yes	String(22)	payment processor transaction ID
gcAmount	yes	Integer	if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
gcCurrency	yes	String(3)	currency
gcResultPayment	yes	Integer	payment result codes
gcHash	yes	String(32)	HMAC MD5 hash (see hash generation)

Direct debit without payment page

After a successful initialization you receive a reference number and an redirect link. The redirect link leads to the payment page. He has to be redirected. This can be achieved by a HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/payment
provided by: GiroCheckout
called by: merchant

POST parameters

Name	Mandatory	Type	Description
merchantId	yes	Integer	merchant ID
projectId	yes	integer	project ID
merchantTxId	yes	String(255)	unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount	yes	Integer	if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency	yes	String(3)	currency EUR = Euro
purpose	yes	String(50)	purpose
type	optional	String(4)	Transaction type (see Transaction types) SALE = Immediate sale (default) AUTH = Reservation of amount
bankcode	optional	String(8)	bank code Mandatory, if no IBAN is set.
bankaccount	optional	String(10)	bank account Mandatory, if no IBAN is set.
iban	optional	String(34)	IBAN of the buyer's bank account without whitespace
accountHolder	yes	String(27)	name of the account holder
mandateReference	optional	String(35)	mandate reference if nothing is specified, a unique number is generated. The reply includes the mandate reference number. numbers: 0 – 9 characters: A – Z and a – z special characters: & \ / = + , : ; . _ - ! ?
mandateSignedOn	optional	String(10)	date (YYYY-MM-DD), when the SEPA mandate was placed. If no date is specified the current date will be used.
mandateReceiverName	optional	String(70)	name of the recipient. If nothing is specified companies name from the master data is used. numbers: 0 – 9 characters: A – Z and a – z special characters: & / = + , : ; . _ - ! ?
mandateSequence	optional	Integer	Sequence type of the SEPA direct debit. 1 = single payment (default) 2 = first payment of a sequence 3 = recurring payment 4 = last payment of a sequence
pkn	optional	String(50)	This field is used to initiate a new transaction without the need for repeating the banking data. create = generate new pseudo card number for the used banking data [Pseudo card number] = Card number of the banking data to be used (see pseudo card number) This feature requires a separate configuration involving a one-time setup fee.
urlNotify	optional	String(2048)	URL, where the notification has to be sent after payment
kassenzeichen	optional	String(255)	Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there.
hash	yes	String(32)	HMAC MD5 hash (see hash generation)

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Lastschrift Transaktion" \
     -d "iban=DE23690516200012345600" \
     -d "accountHolder=Max Mustermann" \
     -d "mandateReference=12345abcde" \
     -d "mandateSignedOn=2014-01-01" \
     -d "mandateReceiverName=mein Shop" \
     -d "mandateSequence=1" \
     -d "hash=28caaa92da143ed83cef2e73213ff162" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/payment

Reply

The reply includes a JSON encoded string. The field rc contains the response code. The response also includes a transaction id and the payment's result.

Parameters

Name	Mandatory	Type	Description
rc	yes	Integer	response code
msg	yes	String(255)	additional information about the response code
reference	optional	String(36)	unique GiroCheckout transaction ID
backendTxId	optional	String(22)	payment processor transaction id
mandateReference	optional	String(35)	mandate reference of the SEPA direct debit
resultPayment	optional	Integer	payment result codes
HEADER parameter
hash	yes	String(32)	HMAC MD5 hash overall the JSON string. (see api call reply)

Example in case of success

hash : 6c8cef797350587f535c8dc65333cf15

{"reference":"d01068e3-50a3-48f5-8185-70835e631809","backendTxId":"1196323_01","mandateReference":"12345abcde","resultPayment":"4000","rc":0,"msg":""}

Example in case of error

hash : 02e0057b4055ab71715d48a4bde7240d

{"reference":"8e0a2a4f-ffee-4ca0-954e-e619038e46ac","backendTxId":"1196322_01","mandateReference":"12345abcde","resultPayment":"5100","rc":0,"msg":""}

Pseudo card number (PKN)

A separate configuration is required for this feature and a one-time setup fee will apply.

A pseudo card number is a reference to bank data used by a buyer (account owner, account number, bank code or IBAN). This reference allows the merchant to offer previously used banking data for reuse by the buyer. If the PKN number is sent in the initialization request of a direct debit transaction, this banking data is pre-filled in the payment form or the payment carried out directly (depending on the desired mode, with or without payment page).

Query pseudo card number information

This function provides PKN information. It returns in its result a PKN as well as the stored baking data (account owner, account number, bank code or IBAN), which has been used in a previous transaction.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/directdebit/pkninfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters

Name	Mandatory	Type	Description
merchantId	yes	Integer	Merchant ID of a direct debit project
projectId	yes	Integer	Project ID of a direct debit project
reference	optional	String(36)	unique GiroCheckout transaction ID
HEADER parameters
hash	yes	String(32)	HMAC MD5 hash overall the JSON string. (see api call reply)

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f" \
     -d "hash=dc1686b621c9cc15bd271390c694258d" \
     https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo

Response

The response is a JSON object. The field rc returns an error code. If rc = 0, the request was successful. The response contains the PKN number, the account owner and the banking data.

Parameters

Name	Mandatory	Type	Description
rc	yes	Integer	response code
msg	yes	String(255)	additional information about the response code
pkn	yes	String(50)	Pseudo card number
holder	yes	String(255)	Account owner (holder)
bankcode	yes	String(8)	Bank code (German BLZ)
bankaccount	yes	String(10)	Account number
iban	yes	String(36)	IBAN
HEADER Parameters
hash	yes	String(32)	HMAC MD5 hash overall the JSON string. (see api call reply)

Example successful request

{"pkn":"ad5c386b38cc9aeb839705d1d10da499","cardnumber":"411111******1111","expiremonth":"2","expireyear":"2016","rc":0,"msg":""}

Example failed request

{"pkn":null,"cardnumber":null,"expiremonth":null,"expireyear":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}

Further transaction types

These transactions reference a previous transaction. The transaction is based on a server-to-server communication and requires no customer interaction (data input).

Provided by: GiroCheckout
Called by: Merchant

Workflow

SVG | PNG | TXT

Shop sends referencing transaction
GiroCheckout redirects transaction to payment processor
Processor transmits result to GiroCheckout
Shop receives response about transaction outcome (Notification)

Capture

When booking, the customer account is debited with an amount and the merchant account is credited. This model is based on the assumption that the associated business case has been completed, e.g. a shopping cart was offered, ordered and delivered to the customer.

Condition: only reserved transactions may be booked
Amount ⇐ Reservation amount
Partial bookings are possible

Refund

A refund is to be used when a previous payment is to be returned fully or partially to the customer.

Condition: may only be applied to the following transaction types:
- Reservation
- Reservation/Booking
Amount ⇐ Transaction amount of the previous transaction

POST Parameter

URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Name	Mandatory	Type	Description
merchantId	yes	Integer	merchant ID
projectId	yes	integer	project ID
merchantTxId	yes	String(255)	unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount	yes	Integer	if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency	yes	String(3)	currency of the transaction according to ISO 4217. EUR = Euro
purpose	optional	String(27)	Purpose of the refund, printed on the bank statement
reference	yes	String(36)	GiroCheckout transaction ID, for which a capture or refund is to be done
kassenzeichen	optional	String(255)	Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there.
hash	yes	String(32)	HMAC MD5 hash (see hash generation)

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "reference=f84e606f-817d-439f-ada1-d37e85cb6314" \
     -d "hash=256b7bb16edbc76871c830d0d623c303" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Response

The response is a JSON object. The field rc returns the error code. If rc = 0, the transaction was successfully initialized. As a response, you receive a transaction number and the redirection URL to the payment form.

Parameters

Name	Mandatory	Type	Description
rc	yes	Integer	response code
msg	yes	String(255)	additional information about the response code
reference	yes	String(36)	unique GiroCheckout transaction ID
backendTxId	yes	String(22)	payment processor transaction id
amount	yes	Integer	the amount of the (partial) transaction, for currencies with decimals use the smallest payment unit, such as Cents or Pennies
currency	yes	String(3)	Currency
resultPayment	yes	Integer	payment result codes
HEADER parameter
hash	yes	String(32)	HMAC MD5 hash overall the JSON string. (see api call reply)

Example of successful transaction

hash : 17790db9c9745b94e1b8db1b22cc7876

{"reference":"e897ef6c-cfd0-4c5e-a932-b15ba24c15cb","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}

Example of failed transaction

hash : 98d9d8b133acf97eb92601fa72d804a0

 {"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","rc":"5100","msg":""}

Void

Void is to be used when an already accepted transaction is not to be executed.

Condition: may only be applied to the following transaction types:
- Reservation (as long as booking has not been done and reservation hasn't expired)
- Reservation/Booking (only on the same day)
- Refund (only on the same day)

POST Parameters

URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Name	Mandatory	Type	Description
merchantId	Yes	Integer	Merchant ID of a direct debit project
projectId	Yes	Integer	Project ID of a direct debit project
merchantTxId	Yes	String(255)	Unique transaction ID of the merchant, Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
reference	Yes	String(36)	GiroCheckout transaction ID that is to be voided
hash	Yes	String(32)	HMAC MD5 hash on the complete JSON string. (see api call reply)

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful. The response includes a transaction number and other information.

Parameters

Name	Mandatory	Type	Description
rc	yes	Integer	response code
msg	yes	String(255)	Additional information about the response code
reference	yes	String(36)	Unique GiroCheckout transaction ID
referenceParent	yes	String(36)	GiroCheckout transaction ID of the original base transaction
merchantTxId	yes	String(255)	Unique transaction id of the merchant
backendTxId	yes	String(22)	Payment processor transaction ID
amount	yes	Integer	Voided amount, if a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
currency	yes	String(3)	Currency
resultPayment	yes	Integer	Payment result codes
HEADER parameter
hash	yes	String(32)	HMAC MD5 hash on the complete JSON string. (see api call reply)

Example in case of success

{"reference":"ef27303f-87b3-465e-9c39-fabfb749d253","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1226723_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}

Example in case of failure

{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

Retrieve sender information

This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, IBAN and BIC of the customer are returned. This information may be used for a refund to the original payer.

API call

URL: https://payment.girosolution.de/girocheckout/api/v2/directdebit/senderinfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters

Name	Mandatory	Type	Description
merchantId	Yes	Integer	merchant ID of a direct debit project
projectId	Yes	Integer	project ID of a direct debit project
reference	Yes	String(36)	GiroCheckout transaction ID
hash	Yes	String(32)	HMAC MD5 hash of the full JSON string. (see api call reply)

Example

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \
     -d "hash=246d1fa2ed97ecff895de974c560f9ec" \
     https://payment.girosolution.de/girocheckout/api/v2/directdebit/senderinfo

Response

The response is a JSON object. The rc field returns an error code. If rc = 0 is returned, the corresponding fields contain the sender information.

JSON Parameters

Name	Mandatory	Type	Description
rc	yes	Integer	response code
msg	yes	String(255)	additional information about the response code in case of error
accountholder	Optional	String(255)	Account holder of the sender account
iban	Optional	String(36)	IBAN of the sender account
bic	Optional	String(11)	BIC of the sender account
HEADER parameter
hash	yes	String(32)	HMAC MD5 hash of the full JSON string. (see api call reply)

Example in case of success

hash : cde71b6b98e8dae709fdc1e17aef885f

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}

Example in case of error

hash : f1d186103b8c4cb59c54ae7b987a9d4c

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}

Girocheckout API

User Tools

Site Tools

Sidebar

Integration

SDK

Others

Table of Contents

Direct Debit

Test data

Workflow

API functions

Overview

Initialize direct debit payment with payment page

Request

POST parameters

Example

Reply

Parameters

Example in case of success

Example in case of error

Notification of the payment result

Request

GET parameters

Reply

Redirection of the customer to merchant

Request

GET parameters

Direct debit without payment page

Request

POST parameters

Example

Reply

Parameters

Example in case of success

Example in case of error

Pseudo card number (PKN)

Query pseudo card number information

Request

POST Parameters

Example

Response

Parameters

Example successful request

Example failed request

Further transaction types

Workflow

Capture

Refund

POST Parameter

Example

Response

Parameters

Example of successful transaction

Example of failed transaction

Void

POST Parameters

Example

Reply

Parameters

Example in case of success

Example in case of failure

Retrieve sender information

API call

POST Parameters

Example

Response

JSON Parameters

Example in case of success

Example in case of error

Page Tools