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

Since January 21st 2021, the new security procedure for credit card payments “3D Secure 2.0” - introduced within the PSD2 efforts - has been mandatory for all payment providers. This API documentation already contains the fields necessary for this (field names beginning with “tds2”), see transaction initialization further below.

Please keep in mind: The parameters related to 3D Secure 2.0 are subject to changes due to modifications in the EMVCo 3-D Secure specs.

The following payment methods are currently supported:

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

1. Customer visits checkout section of the shop in order to pay for his order
2. Shop initializes a paypage transaction (Initialization)
3. GiroCheckout initializes transaction internally and returns paypage URL
4. Shop redirects customer to the paypage, customer selects payment method
5. Paypage initializes payment in GiroCheckout
6. GiroCheckout returns URL of the payment form to the paypage
7. Paypage redirects customer to the payment form of the payment processor, customer enters data and pays
8. Payment processor informs GiroCheckout about transaction result
9. GiroCheckout notifies shop about transaction result (Notification)
10. Shop processes transaction result
11. Shop sends HTTP status code to GiroCheckout
12. GiroCheckout redirects customer back to the shop
13. Shop displays result to customer

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: S-Public Services GmbH
Called by: Merchant

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.

URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init

  numbers: 0 – 9  
  characters: A – Z and a – z  
  special characters: & \ / = + , : ; . _ \ - ! ? 

  numbers: 0 – 9  
  characters: A – Z and a – z  
  special 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

This is a JSON formatted object that has a hierarchical structure (2 levels) and contains the following sub-objects:

• billingAddress
• shippingddress
• homePhoneNumber
• mobilePhoneNumber
• workPhoneNumber
• cardholderAccountInfo
• tdsMerchantRiskIndicators
• tdsRequestorAuthenticationInformation
• tdsTransactionAttributes

Generally, the following fields (all optional) are available (fields in sub-objects are displayed as [sub-object name].[field]):

{
  "email": "myemail@example.com",
  "addressesMatch": "false",
  "billingAddress": {
    "line2": "Beim Nachbarn klingeln",
    "line3": "zw. 22-24 Uhr",
    "state": "BW"
  },
  "shippingAddress": {
    "city": "Berlin",
    "country": "DE",
    "line1": "Unter den Linden 1",
    "line2": "Brandenburger Tor",
    "line3": "(linker Bogen)",
    "state": "BER"
  },
  "homePhoneNumber": {
    "country": "49",
    "regional": "75519209309"
  },
  "mobilePhoneNumber": {
    "country": "49",
    "regional": "17093902978"
  },
  "workPhoneNumber": {
    "country": "49",
    "regional": "8938928938"
  },
  "cardholderAccountInfo": {
    "accountAgeIndicator": "more30less60",
    "passwordChangeIndicator": "never",
    "paymentAccountAgeIndicator": "less30",
    "accountChange": "now",
    "shippingAddressAgeIndicator": "more60",
    "shippingNameIndicator": "different",
    "suspiciousAccountActivity": "false",
    "provisioningDayCount": 10
  },
  "tdsMerchantRiskIndicators": {
    "deliveryTimeframe": "overnight",
    "deliveryEmailAddress": "hans-mueller@example.com",
    "giftCardAmount": 0,
    "giftCardCount": 2,
    "giftCardCurrency": "EUR",
    "preOrderDate": "2020-12-20",
    "preOrderPurchaseIndicator": "available",
    "reorderItemsIndicator": "first",
    "shippingIndicator": "store"
  },
  "tdsRequestorAuthenticationInformation": {
    "authenticationData": "123Hdajkd/dasjdkk",
    "authenticationTimestamp": "2020-11-09T12:09:09",
    "authenticationMethod": "ownCredentials"
  },
  "tdsTransactionAttributes": {
    "purchaseInstalmentData": 2,
    "recurringExpiry": "2020-11-30",
    "recurringFrequency": 1234,
    "type": "quasiCash"
  }
}

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.

JSON array with item objects:

[ {
    "name" : "Bobbycar",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helm",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]

The result of a transaction is transmitted on 2 parallel paths. The notification and the redirect.

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.

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

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.

These transactions reference a previous transaction. They are based on a server to server communication and require no customer interaction (data entry). In the case of the payment page, please bear in mind that these transaction types (capture and refund) will refer to the underlying transaction carried out previously and therefore the action is only admissible if the corresponding payment method supports this.

Example:

If a payment link is used to pay an invoice and the customer chooses the payment method creditcard, this transaction may later be refunded through the use of the payment page transaction reference number. If the initial transaction was an authorization (reservation), the same reference number may be used to trigger the capture of the reserved amount. However, if the customer made the payment with giropay instead, where there is no reservation or refund, these attempts will be denied with an error message.

Furthermore it is important to be aware that depending on how the payment or donation page was initialized (especially regarding the single parameter), there may be several payments that were completed through the page. In this case, where more than one successful payment is associated to the payment page reference number, the optional parameter 'txreference' must be specified, that will then contain the precise reference number of the payment transaction. Remember that this number is returned in both notification and redirect of the payment transaction in the parameters 'gcReference' and 'reference', respectively).

Provided by: GiroCheckout
Called by: Merchant

1. Shop sends reference to previous credit card transaction
2. GiroCheckout sends transaction to credit card processor
3. credit card processor transmits result to GiroCheckout
4. Shop receives reply on transaction outcome (Notification)

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

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialized. The response also includes a transaction id and other information about the transaction.