Since January 1st 2021, the new security procedure for credit card payments “3D Secure 2.0” - introduced within the PSD2 efforts - becomes 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.

Detailed information on the transaction types.

After a successful initialization the merchant receives a reference number and a redirect link. The redirect link leads to the payment page. The customer (buyer) must be redirected to this link. This can be achieved by an HTTP redirect header, an HTML page with a corresponding meta tag or a JavaScript redirect.

Provided by: GiroCheckout
Called by: merchant

1. Buyer selects payment type “credit card”
2. Shop initializes credit card transaction (Initialization)
3. GiroCheckout initializes transaction at CC processor
4. Credit card processor transmits result to GiroCheckout
5. Shop receives response about transaction outcome (transaction ends in case of error)
6. Shop sends redirect URL to customer browser
7. Customer browser redirects to credit card processor
8. Credit card processor displays payment form
9. Customer authorizes transaction
10. Credit card processor carries out transaction
11. Credit card processor transmits result to GiroCheckout
12. GiroCheckout notifies Shop about transaction outcome (Notification)
13. Shop processes transaction outcome
14. Shop sends HTTP status code to GiroCheckout
15. GiroCheckout sends merchant redirect (return to merchant page) to Credit card processor
16. Customer clicks “Back to shop” (Return)

As shown in the workflow, different API calls are involved in a credit card transaction. During the payment process a 3D-Secure check may be applied as well, but this depends solely on the credit card issuing institute and does not affect merchant or PSP in any way.

1. Initialize transaction
2. 3D-Secure check (optional)
3. Payment result notification to merchant
4. Buyer redirection to the merchant (triggered by buyer)

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 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 a redirect URL to the payment page.

The result of an initialized transaction will be submitted to the merchant through URL specified in the urlNotify parameter. This notification should be used to update the order status in the merchant's system.

The result of the payment is contained in the field gcResultPayment.

URL: notifyUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

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

After completing the payment, the customer may return to the merchant through a link. This return only happens once the customer clicks the “cancel” or “return to shop” button and is not done automatically.

URL: redirectUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

These transactions reference a previous transaction. They are based on a server to server communication and require no customer interaction (data entry).

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.

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

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.

A pseudo card number is a reference to a credit card that has been used recently by the buyer (card number and expiration date). This reference allows the merchant to offer a previously used credit card for reuse by the customer. If the PKN is transmitted along during the initialization of a credit card transaction, the card number and expiration date is pre-filled in the payment form. The customer needs only to enter the validation code and may then carry out the payment.

This function allows access to PKN information. It returns as a result both the PKN and the saved credit card information (masked credit card number, expiration date), which were used for a previous transaction.

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

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 the PKN number, the (masked) credit card number and the expiration date.

The transaction data is transmitted and the result of the credit card payment is returned immediately. This function is used for recurring credit card payments, such as subscriptions.

The following steps are necessary to implement a recurring payment:

1. Carry out a normal credit card transaction with pkn=create (see Initialize Payment)
2. Obtain pseudo card number (PKN) (see Query PKN information)
3. Store this PKN
4. On the next recurring payment, initialize a payment transaction (use correct end point, see Recurring or PKN transaction), but set parameter pkn and let recurring=1.

In order to carry out a recurring payment without customer intervention, use the following function.

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

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful.

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, masked card number, expiration date and card brand of the customer card are returned.

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

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.