Table of Contents

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:

Direct debit with payment page

buyermerchantGiroCheckoutpayment processor1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2013 by GiroSolution AG

  1. Buyer chooses direct debit payment method
  2. merchant initialises direct debit transaction (initialising direct debit transaction)
  3. GiroCheckout initialises transaction at direct debit processor
  4. direct debit processor submits response to GiroCheckout
  5. merchant gets response about initialisation (if an issue occurs the transaction is finished)
  6. merchant sends redirect URL to buyer
  7. the buyer's browser redirects buyer to the payment form
  8. direct debit processor shows payment form
  9. buyer authorises payment
  10. transaction is beeing processed
  11. direct debit processor submits payment result to bank
  12. GiroCheckout notifies merchant about the payment result (payment result norification)
  13. merchant processes result
  14. merchant sends HTTP statuscode to GiroCheckout
  15. GiroCheckout sends merchants redirect page to bank
  16. buyer clicks “back to the shop” and gets redirected to the merchant (buyer redirection)

Direct debit without payment page

buyermerchantGiroCheckoutbank1 2 3 4 5 6 (c)2013 by GiroSolution AG

  1. buyer choses direct debit payment and fills in his IBAN
  2. merchant subits direct debit payent to GiroCheckout (direct debit without payment page)
  3. GiroCheckout submits direct debit payent to the bank
  4. bank replies and submits payment result to GiroCheckout
  5. GiroCheckout replies merchant
  6. 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.

  1. Initialize transaction
  2. Request account information from customer
  3. Transmit payment information to merchant
  4. 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.

  1. 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
mandateReferenceoptionalString(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
Mandatory, if bankcode and bankaccount are not set.
accountHolder optionalString(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

ShopGiroCheckoutAbwickler1 2 3 4 (c)2016 by GiroSolution AG

  1. Shop sends referencing transaction
  2. GiroCheckout redirects transaction to payment processor
  3. Processor transmits result to GiroCheckout
  4. 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"}