giropay

Integrate giropay and allow merchants to offer secure online payments via over 1500 banks and saving banks in Germany.

Payment Method Properties

MarketsDE
Processing currenciesEUR
Consumer currenciesEUR
Settlement currenciesEUR
Minimum payment amount1.00 EUR
Maximum payment amountNo limit

- Up to 10.000 EUR - payment guaranteed*
- Over 10.000 EUR - payment not guaranteed
Recurring Payment SupportYes (through SEPA Direct Debit)
Separate Chargeback SupportNo
Tmeout1 hour
Refund- Full
- Partial
- Multiple Partial
Refund validity365 days
ChargebackNo
Sandbox availabilityPPRO provided

*giropay contractually guarantees the payment for up to 6 weeks after the initial transaction.

Make an giropay Payment

To make an giropay payment, you'll need to provide the following data when calling our /v1/payment-charges API:

Data FieldRequiredDescription
paymentMethodYGIROPAY
amount.valueYThe amount to be paid in the smallest units of the currency used.
amount.currencyYEUR The currency used for the payment
consumer.nameYFull name of the consumer
consumer.countryYThe country where the consumer is shopping
authenticationSettings: REDIRECT
settings.returnUrl
YSpecify the URL that the consumer should be redirected back to after completing the payment
webhooksUrlYou should include the endpoint URL where you want to receive webhooks for updates to the payment charge.

Request

POST /v1/payment-charges

{
  "paymentMethod":"GIROPAY",
  "amount":{
    "value":1000,
    "currency":"EUR"
  },
  "consumer":{
    "name": "Connor Summer",
    "country": "DE"
  },
  "webhooksUrl": "https://your-webhooks-endpoint/",
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
         "returnUrl": "https://example.com/order_details?order_id=12345"
      }
    }
  ]
}

Response

You'll receive one of our standard payment charge responses (see potential responses in the API Reference)

{
  "id": "charge_X0O78tadFHrZCbGhktcPk",
  "status": "AUTHENTICATION_PENDING",
  "instrumentId": "instr_2134sdfjk340sdfjk23ksd",
  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://hpp.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Consumer Authentication

giropay requires authentication by the consumer, which they do via their bank's online environment. You will need to redirect their browser to giropay's payment page using the link provided in the requestUrl field of the REDIRECT authentication method response. On giropay's payment page to choose their bank

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer logs into their bank and approves the payment. After this, the charge will transition to the CAPTURED state.

Handling the Payment Result

The consumer will be redirected to the authenticationMethods.settings.returnUrl provided in the initial payment charge creation request, depending on whether the authorization is a success, a failure, or if the user cancelled/aborted the flow.

If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED state.

You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED.

Recurring Payments

Since giropay currently does not offer native recurring payments, SEPA Direct Debits are used for all subsequent charges. You can set up giropay recurring payments easily using PPRO Payment Agreements.

❗️

When you offer giropay in the checkout for a recurring product, you should get explicit approval (mandate) from the consumer to have their account charged on a recurring basis via direct debit. SEPA Direct Debits have a chargeback risk, which can be reduced by being as transparent with the consumer as possible.

When the consumer selects giropay for their recurring payment and agrees to a direct debit mandate, you'll need to generate an ID for this mandate and store it in your system. This ID is then passed to PPRO when you create the payment agreement.

To set up a payment agreement for giropay, the payer needs to authorise the first transaction. If you don't include an initialPaymentCharge, the customer will be charged a small verification amount to create a link-only payment agreement. This amount would be automatically refunded by PPRO. To reduce friction, we advise that this amount and the fact that it'll be refunded is mentioned on the checkout.

Create the Payment Agreement

To set up a recurring agreement for giropay, you'll need to provide the following data when calling our /v1/payment-agreements API:

Data FieldRequiredDescription
paymentMethodYGIROPAY
amount.valueYThe amount of the recurring charge in the smallest units of the currency used.
amount.currencyYEUR The currency used for the payment
consumer.nameYFull name of the consumer
consumer.countryYThe country where the consumer is shopping
instrument: BANK_ACCOUNT
details.debitMandateId
YThe ID of the direct debit mandate you have generated and stored in your system.
authenticationSettings: REDIRECT
settings.returnUrl
YSpecify the URL that the consumer should be redirected back to after completing the payment
initialPaymentCharge: amount.valueThe amount to be paid in the smallest units of the currency used. This is required if you want to immediately capture the charge.
initialPaymentCharge: amount.currencyEUR The currency used for the payment
webhooksUrlYou should include the endpoint URL where you want to receive webhooks for updates to the agreement and payment charges.

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify the exact amount.value and amount.currency of the first payment.

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Request

POST /v1/payment-agreements

{
  "paymentMethod":"GIROPAY",
  "amount":{
    "value":1000,
    "currency":"EUR"
  },
  "consumer":{
    "name": "Connor Summer",
    "country": "DE"
  },
  "instrument": {
     "type": "BANK_ACCOUNT",
     "details": {
        "debitMandateId": "YOURGENERATEDMANDATEID"
      }
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
         "returnUrl": "https://example.com/order_details?order_id=12345"
      }
    }
  ],
  "initialPaymentCharge": { //if first payment should be immediately captured
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "paymentDescriptor": "PPRO - ORDER 1234"
  },
  "webhooksUrl": "https://your-webhooks-endpoint/"
}

Response

You'll receive a standard payment agreement response (see potential responses in the API Reference)

{
  "id": "agrmt_X0O78tadFHrZCbGhktcPk",
  "status": "AUTHENTICATION_PENDING",
  "initialPaymentChargeId": "charge_DOS43DF023dka42kdTwGa", //if initialPaymentCharge was specified
  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://hpp.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Make Subsequent Recurring Charges

Once the first successful giropay payment has been made with a Payment Agreement, you can make subsequent recurring charges by calling POST /v1/payment-agreements/{agreement_id}/payment-charges

These subsequent charges are processed via SEPA Direct Debit and have a chargeback risk.

Additional Information

Transactions may change from any state at any time. This change occurs especially from a FAILED to a CAPTURED state. CAPTURED is considered a stable state.