Table of Contents

giropay

Owing to the merge of the giropay and paydirekt companies, the giropay API is currently subject to several changes. This page gives you all the necessary information that will help you assess whether you need to adapt your integration on your end or not, and if so, which changes are needed.

Migration guide

In this section, we will detail what exactly you need to consider when preparing your system for the new giropay.

Please select your most relevant subject from the following list:


What changes were made to the GiroCheckout API regarding giropay?

Changes in the parameter fields

  1. The fields bic, iban and the info fields (info1Label, info1Text etc.) are no longer available.
    The required information regarding the client's bank are now directly obtained on the side of giropay and/or the customer bank and are no longer sent along in the initialization request. Please remove these fields from your request if you are still using them.
  2. Information regarding the shopping cart contents can be optionally passed along in the cart field.

shoppingCartType

  1. The shoppingCartType should now be always present in a giropay transaction.
  2. The field is optional but impacts other fields of the API.
  3. Possible values:
    • PHYSICAL = All goods in the cart are of a physical nature, shippingAddresseFirstName, shippingAddresseLastName, shippingZipCode, shippingCity and shippingCountry are mandatory.
      All other fields may be passed optionally (see API documentation).
    • DIGITAL = All goods in the cart are of a digital nature (require no shipping), shippingAddresseFirstName, shippingAddresseLastName and shippingEmail are mandatory.
      All other fields may be passed optionally (see API documentation).
    • MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given), shippingAddresseFirstName, shippingAddresseLastName, shippingZipCode, shippingCity and shippingCountry are mandatory.
      All other fields may be passed optionally (see API documentation).
    • ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary),
      All other fields may be passed optionally (see API documentation).
    • AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).
      All other fields may be passed optionally (see API documentation).

Integration via an SDK

The SDKs (PHP, Java, .NET) are already up to date and support the new giropay. You can find the documentation under the following links:


Municipal Customers: What to consider regarding authorities payments?

Summary

Transactions with the shoppingCartType “AUTHORITIES_PAYMENT” don't need to pass any further mandatory fields.

Municipal Customers: What to consider for integrations via the Payment Page for authorities payments?

Transactions with the shoppingCartType “AUTHORITIES_PAYMENT” for municipal customers don't need to specify any additional mandatory fields.


Merchant Customers: What to consider for integrations via the API?

Changes in the parameter fields

  1. The fields bic, iban and the info fields (info1Label, info1Text etc.) are no longer available.
    The required information regarding the client's bank are now directly obtained on the side of giropay and/or the customer bank and are no longer sent along in the initialization request. Please remove these fields from your request if you are still using them.
  2. Information regarding the shopping cart contents can be optionally passed along in the cart field.

shoppingCartType

  1. The shoppingCartType should now be always present in a giropay transaction.
  2. The field is optional but impacts other fields of the API.
  3. Possible values:
    • PHYSICAL = All goods in the cart are of a physical nature, shippingAddresseFirstName, shippingAddresseLastName, shippingZipCode, shippingCity and shippingCountry are mandatory.
      All other fields may be passed optionally (see API documentation).
    • DIGITAL = All goods in the cart are of a digital nature (require no shipping), shippingAddresseFirstName, shippingAddresseLastName and shippingEmail are mandatory.
      All other fields may be passed optionally (see API documentation).
    • MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given), shippingAddresseFirstName, shippingAddresseLastName, shippingZipCode, shippingCity and shippingCountry are mandatory.
      All other fields may be passed optionally (see API documentation).
    • ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary),
      All other fields may be passed optionally (see API documentation).
    • AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).
      All other fields may be passed optionally (see API documentation).

Merchant Customers: What to consider for integrations via the Payment Page?

Summary

No special changes are required here.


Comparison old and new API

An overview of the mappings between the APIs

GiroCheckout giropay GiroCheckout Payment Page Mandatory Comment
merchantId (8) merchantId (8) Yes GiroCheckout authentication
projectId (8) projectId (8) Yes GiroCheckout authentication
merchantTxId (255) merchantTxId (255) Yes
amount (7) amount (7) Yes Amount in cents
currency (3) currency (3) Yes Only EUR allowed
purpose (27) purpose (50) Yes Same as before, 27 characters for giropay
shoppingCartType shoppingCartType Optional Type of the shopping cart. The following values are allowed:
PHYSICAL = All goods in the cart are of a physical nature,
DIGITAL = All goods in the cart are of a digital nature (require no shipping),
MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given),
ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary),
AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).
shippingAddresseFirstName(100) paydirektShippingFirstName (100) Yes / Optional First name of shipping address, mandatory for shoppingCartTypes PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT.
shippingAddresseLastName (100) paydirektShippingLastName (100) Yes / Optional Last name of shipping address, mandatory for shoppingCartTypes PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT.
shippingCompany (100) paydirektShippingCompany (100) Optional Company name
shippingAdditionalAddressInformation (100) paydirektShippingAdditionalAddressInformation (100) Optional Additional address info
shippingStreet (100) paydirektShippingStreet (100 Optional Street
shippingStreetNumber (100) paydirektShippingStreetNumber (100) Optional House number
shippingZipCode (10) paydirektShippingZipCode (10) Yes / Optional Postal code of the shipping address. Mandatory for shoppingCartTypes PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT.
shippingCity (100) paydirektShippingCity (100) Yes / Optional City of the shipping address. Mandatory for shoppingCartTypes PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT.
shippingCountry (2) paydirektShippingCountry (2) Yes / Optional 2-letter country code (ISO 3166-1). Mandatory for shoppingCartTypes PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT.
shippingEmail (255) paydirektShippingEmail (255) Yes / Optional Email address of the buyer. Mandatory for shoppingCartType DIGITAL, optional for all others.
merchantReconciliationReferenceNumber (30) merchantReconciliationReferenceNumber (30) Optional (30) Additional information for the payment settlement that is displayed in the purpose of the bank statement.
cart cart Optional Shopping cart
deliveryType deliveryType Optional The destination of a shipment. The default value is STANDARD. STANDARD: The goods are delivered to an ordinary postal address.PACKSTATION: The goods are delivered to a self-service parcel terminal. STORE_PICKUP: The goods are collected from the store.
bic (8-11) Optional No longer supported
iban (12-32) Optional No longer supported
info1Label (30) Optional No longer supported
info1Text (80) Optional No longer supported
info2Label (30) Optional No longer supported
info2Text (80) Optional No longer supported
info3Label (30) Optional No longer supported
info3Text (80) Optional No longer supported
info4Label (30) Optional No longer supported
info4Text (80) Optional No longer supported
info5Label (30) Optional No longer supported
info5Text (80) Optional No longer supported
urlRedirect Yes Redirect to the integrator
urlNotify Yes Notification to the integrator
hash Yes GiroCheckout authentication

Settlement

FAQ

The current version of our list of frequently asked questions and their answers is available in German and English through the following links.

German FAQ

English FAQ