Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

giropay

Learn how to accept giropay payments.

giropay is the official implementation of German banks for online banking. It is supported by most German public and cooperative banks. 

When paying with giropay, the shopper is redirected to their bank's website or app to complete the payment. For most giropay payments, you'll receive immediate confirmation of whether the payment was successful. For a small number of payments you will not receive an immediate confirmation, and will need to rely on a notification to confirm whether the payment was successful.

Payment Type Payment flow Recurring Refunds Partial Refunds Captures Partial Captures Chargebacks
Online Banking Redirect Yes, via SEPA Yes Yes No No No*

*There is a chargeback risk for recurring payments, since they are processed via SEPA Direct Debit

You can accept giropay payments with:

Integrate with Checkout mobile SDKs

Our Checkout SDKs support giropay payments without any additional configuration. 

Integrate with API

In this section, we show you the API integration steps for giropay. 

Before you begin this section, make sure you read and understand our API Integration guide.

Step 1: Collect shopper details

To collect the shopper's details, add our pre-built giropay Component to your payments form:

  1. Make sure that you have already added the Components JavaScript file and the required configuration on your payments page.

  2. Create a DOM element, placing it where you want the giropay form to be rendered: 

    <div id="giropay"></div>
  3.  Create an instance of the giropay Component, and mount it: 

    const giropay = checkout.create("giropay").mount("#giropay");
  4. When the onChange event is triggered and when state.isValid is true, collect the encrypted values passed in the state.data. You'll use these to make the payment. If you wish to override the function on the main Adyen Checkout instance, you can also define an onChange event on the Component level.

Step 2: Make a payment

To initiate a giropay payment, make a /payments API call, providing:

  • reference: Your unique reference for this payment.
  • amount
  • paymentMethod.typegiropay
  • paymentMethod.bic: The value of the bic provided in the state.data object.

  • returnUrl: The URL that your shopper is redirected to after they have completed the payment.
{
  "merchantAccount":"YourMerchantAccount",
  "reference":"giropay test",
  "amount":{
    "currency":"EUR",
    "value":"1000"
  },
  "paymentMethod":{
    "type":"giropay",
    "bic":"DEUTDE2H"
  },
   "returnUrl":"https://your-company.com/..."
}

This returns a /payments response containing:

  • resultCodeRedirectShopper.
  • redirect object containing a url. You'll need this URL in the next step.
{
  "resultCode":"RedirectShopper",
  "details":[
    {
      "key":"payload",
      "type":"text"
    }
  ],
  "paymentData":"abcxyz...",
  "redirect":{
    "method":"GET",
    "url":"https://test.adyen.com/hpp/skipDetails.shtml?brandCode=???&sdfsdf..."
  }
}

Step 3: Redirect shopper

Redirect the shopper to the URL specified at redirect.url.

The redirect.url enables the shopper to approve the payment on their bank's website or app.

When the shopper has completed the payment, they return back to your website or app using the returnUrl you specified when you made the /payments request. The returnUrl is appended with a URL-encoded payload. You'll use the payload in the next step to verify the payment. If any other parameters are appended, ignore them.

    https://your-company.com/?payload=sdfsdf...&type=complete&resultCode=authorised

Step 4: Present payment result

  1. To verify the result of the payment, URL decode the payload and sumbit it in a POST request to the /payments/details endpoint.

    {
      "details":{
        "payload":"sdfsdfsdf..."
      }
    }

    The response will contain a pspReference, which is our unique identifier for this payment, and a resultCode

  2. Use the resultCode to present the result of the payment to your shopper via your website or app. If the shopper failed to return to your website or app after completing the payment, you will not receive a resultCode. To track the status of the payment, you should use notifications.

giropay result codes

 The resultCode values you can receive for giropay are:

  • Authorised – The payment was successful. You will receive the funds in 1-2 working days.
  • Refused –  The payment was not completed. Ask the shopper to try the payment again. For a description of the refusal reason, check the Payment Details page in your Customer Area.
  • Cancelled – The payment was not completed. Ask the shopper to try the payment again.
  • Pending: The shopper has completed the payment but the final result is not yet known. Inform the shopper that you've received their order, and are waiting for the payment to be completed. When the shopper has completed the payment, you will receive a successful AUTHORISATION notification

To find out more about result codes and how you can action them, refer to Result codes

giropay notifications

Our notifications are webhooks informing you of important events related to your account. In most cases, the resultCode you receive at the end of the payment flow already indicates whether the payment was authorised. In other cases, we can only inform you of the outcome of a payment by means of a notification. You'll need to rely on notifications when:

  • The resultCode is Pending or Received.
  • You didn't receive a resultCode, for example because the shopper failed to return to your website or app after completing the payment.

To inform you of the outcome of a payment, we send you a notification with:

  • eventCode: AUTHORISATION.
  • pspReference: Adyen's unique reference associated with the payment request.
  • success: Indicates the outcome of the payment. Possible values:

    • true: The payment was authorised.
    • false: The payment failed.

AUTHORISATION is just one of the events that trigger a notification. Refer to Notification webhooks to accept notifications and learn about their structure and content.

Recurring giropay payments

If you have a subscription or recurring business model, we recommend creating a shopper token.

Although giropay does not support recurring payments, you can make recurring payments for a giropay shopper by tokenizing their payment details. When you create a shopper token from a giropay payment, we'll store the shopper's SEPA details with the token. You can use this token to make recurring payments using SEPA Direct Debit.

You can create a shopper token with either the SDK or API integrations, but to make recurring payments with the token you'll need to use the  /payments endpoint.

We strongly recommend that you request explicit permission from the shopper if you intend to make recurring payments. Being transparent about the payment schedule and the amount they will be charged will reduce the risk of chargebacks.

Create shopper token

Tokenize the shopper's payment details when you make the initial giropay payment. The steps for doing this depend on whether you integrated with our Checkout SDKs or our API integration.

Checkout SDKs

  1. When you call /paymentSession to create a payment session, additionally include:

    • shopperReference: Your unique ID for this shopper.

    • enableRecurringtrue
  2. When you receive the response (or the notification) that the payment was authorised, note the recurringDetailReference. This is the token you will need to make recurring payments for this shopper.

API integration

  1. When you call /payments to make a payment, additionally include:
    • shopperReference: Your unique ID for this shopper.
    • paymentMethod.storeDetailstrue
  2. When you receive the notification that the payment was authorised, note the recurringDetailReference. This is the token you will need to make recurring payments for this shopper.

Make recurring payments

Any recurring payments for the giropay shopper are made as a SEPA Direct Debit payment.

  • Make a /payments request for a SEPA payment, and additionally include:

    • paymentMethod.typesepadirectdebit.
    • recurringDetailReference: Token received back from the giropay payment.
    • shopperReference: The same shopper ID you used to create the shopper token.
    • shopperInteractionContAuth.
    {
       "amount":{
          "value":1000,
          "currency":"EUR"
       },
       "paymentMethod":{
          "type":"sepadirectdebit",
          "recurringDetailReference":"7219687191761347"
       },
       "reference":"Your Reference Here",
       "merchantAccount":"YourMerchantAccount",
       "shopperReference":"YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
       "shopperInteraction":"ContAuth"
    }

    If the payment was successfully received, the response will contain a Received resultCode and a pspReference, which is our unique identifier for this transaction. You can track whether the payment was successful using notifications.

Testing giropay payments

Before making live giropay payments, use the following details to test your integration:

Bank Name BIC Customer name IBAN Account ID Bankleitzahl
Testbank Fiducia GENODETT488 Any DE36444488881234567890 1234567890 44448888

After selecting Testbank Fiducia, you are redirected to a page where you can select different statuses to simulate with. We recommend testing each giropay status code:  

sc extensionSc importance
10 4000 The payment was successful.
20 2000,2100,2200,2300,2400,2500,2600,2700,3100,3900,4900 The payment was not successful.
30 4500 Status of the payment is unknown.
40 0 Bank is not unlocked for giropay.

You can check the status of a giropay test payment in your Customer Area > Transactions > Payments.

See also