User Tools

Site Tools


Translations of this page:
en:girocheckout:giropay-overview:start

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?

Purpose

  1. The purpose field is being reduced in maximum length from 27 to 20 characters and may now only contain certain characters.
  2. Make sure that you only use characters from the following list: A-Z a-z 0-9 + ? / - : ( ) . , ' (NO blanks!)
  3. Make sure that the maximum length of 20 characters is not exceeded.

If the above criteria are not met for the passed purpose field, your request will be denied.

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. Changes only affect the purpose field.

  1. The purpose field is being reduced in maximum length from 27 to 20 characters and may now only contain certain characters.
  2. Make sure that you only use characters from the following list: A-Z a-z 0-9 + ? / - : ( ) . , ' (NO blanks!)
  3. Make sure that the maximum length of 20 characters is not exceeded.

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

Summary

  • The Payment Page API allows up to 50 characters for the purpose field.
  • Nevertheless, the purpose is adjusted according to the selected payment method by the Payment Page. For giropay, forbidden characters are removed and the result is then truncated to the maximum allowed length of 20 characters.
  • The permitted characters are: A-Z a-z 0-9 + ? / - : ( ) . , ' (NO blanks!)
  • In case of giropay, thus, please bear in mind that the purpose is cut off after 20 characters, if is it longer than that.
  • So please make sure that all relevant information is located within the first 20 characters and no unallowed characters are used.
  • 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?

Purpose

  1. The purpose field is being reduced in maximum length from 27 to 20 characters and may now only contain certain characters.
  2. Make sure that you only use characters from the following list: A-Z a-z 0-9 + ? / - : ( ) . , ' (NO blanks!)
  3. Make sure that the maximum length of 20 characters is not exceeded.

If the above criteria are not met for the passed purpose field, your request will be denied.

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

  • The Payment Page API allows up to 50 characters for the purpose field.
  • Nevertheless, the purpose is adjusted according to the selected payment method by the Payment Page. For giropay, forbidden characters are removed and the result is then truncated to the maximum allowed length of 20 characters.
  • The permitted characters are: A-Z a-z 0-9 + ? / - : ( ) . , ' (NO blanks!)
  • In case of giropay, thus, please bear in mind that the purpose is cut off after 20 characters, if is it longer than that.
  • So please make sure that all relevant information is located within the first 20 characters and no unallowed characters are used.

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 Limit to 20 characters and validate like field orderid
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

en/girocheckout/giropay-overview/start.txt · Last modified: 2022/07/29 18:51

Page Tools