General

The merchant starts by sending the request for a Giropay payment to a BPE transaction gateway. The gateway will then process the request and send a response to the merchant. If the request is sent to a gateway without a customer redirect, the response will contain a redirect URL to which the customer must be redirected. If in the original request the customer was redirected along to the Buckaroo public gateway, the customer is automatically redirected to Giropay page at his bank by the transaction gateway. Once the customer reaches this page, he can enter his banking information and verify the payment is executed immediately and the customer will be redirected back to the merchant website, along with the result. Additionally, the Payment Engine will also perform a Transaction Push, with the status of the payment.

Servicecodes and actions

The Giropay service uses the service code: giropay.

The Giropay service supports the following actions: Pay, Refund. For both actions the channel "WEB" is supported.

Recurring payments

It is also possible to use a Giropay transaction as a reference transaction for recurring SEPA Direct Debit transactions. To do this, add the basic parameter "StartRecurrent" with value "True" to your Giropay API request. Once the payment has been successfully completed by the customer and the money has been received by Buckaroo (the latter can take up to a week), a recurring SEPA direct debit request can be performed and accepted. We advise to wait at least a week before performing a recurring payment request. In any case, if the request returns a failure (because the money hasn't arrived yet) it should be performed again later in order for it to be accepted and executed. Please see the SEPA Direct Debit section for an explanation of the "PayRecurrent" request.

Pay

The default action for Giropay is Pay. Upon receiving the input, the consumer will be redirected to Giropay page at his bank for verification and confirmation of the payment. After completion at the bank site, the customer is redirected back to the merchant site.

View in playground

Request


JSON gateway request

bic
Required

The international bankcode identifying the customer's bank. This information is required, but it is possible to let the customer fill it in on the Buckaroo checkout page. In that case, leave the bic parameter out and add the basic parameter "ContinueOnIncomplete" with a value of 1.

CustomerIBAN

The customer's IBAN with which he/she wants to perform the Giropay transaction. If the customer tries to pay with a different IBAN, the transaction will be rejected by Giropay. This parameter can be used to prevent fraud: when a customer fills in IBAN B on your website and on the Giropay page tries to pay with IBAN A, they will not be able to pay. If they fill in IBAN A on your website which you know is not theirs, you can block them from starting a payment on your website. Please note that blocking the payment on your website is something you have to implement yourself.

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 10.00,
   "Invoice": "testinvoice 123",
   "Services": {
      "ServiceList": [
         {
            "Name": "giropay",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "bic",
                  "Value": "GENODETT488"
               },
               {
                  "Name": "CustomerIBAN",
                  "Value": "NL13TEST0123456789"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

consumerBIC

The international bankcode identifying the customer's bank.

JSON

copy
{
   "Key": "6473D552EB7F4074817A9A6F1BFBxxxx",
   "Status": {
      "Code": {
         "Code": 791,
         "Description": "Pending processing"
      },
      "SubCode": {
         "Code": "S002",
         "Description": "An additional action is required: Verify at Giropay"
      },
      "DateTime": "2018-04-16T16:05:28"
   },
   "RequiredAction": {
      "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=D71F06AB0C9540FC8C76BF7FA76xxxx",
      "RequestedInformation": null,
      "PayRemainderDetails": null,
      "Name": "Redirect",
      "TypeDeprecated": 0
   },
   "Services": [
      {
         "Name": "giropay",
         "Action": null,
         "Parameters": [
            {
               "Name": "consumerBIC",
               "Value": "GENODETT488"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "giropay",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10.00,
   "TransactionType": "C241",
   "MutationType": 1,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "397BB56968074AE7AC99EFC8A264xxxx"
}

Push


JSON push response

When the consumer has completed the payment, the transaction status will be pushed with a succes status.

consumerBIC

The international bankcode identifying the customer's bank.

consumerBankleitzahl

The national bank code of the customer's account, which is part of their IBAN.

consumerIBAN

The customer's IBAN. This parameter is only returned in the push if the parameter was sent along in the original request.

JSON

copy
{
   "Transaction": {
      "Key": "8A69B71E57244B71866104A0D636xxxx",
      "Invoice": "testinvoice 123",
      "ServiceCode": "giropay",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2018-04-16T16:04:16"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountDebit": 10,
      "TransactionType": "C241",
      "Services": [
         {
            "Name": "giropay",
            "Action": null,
            "Parameters": [
               {
                  "Name": "consumerBIC",
                  "Value": "GENODETT488"
               },
               {
                  "Name": "consumerBankleitzahl",
                  "Value": "44448888"
               },
               {
                  "Name": "consumerIBAN",
                  "Value": "NL13TEST0123456789"
               }
            ],
            "VersionAsProperty": 2
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 1,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": null,
      "PayerHash": null,
      "PaymentKey": "C5D95257D04343E2BC34576D309Exxxx"
   }
}

Refund

To refund a successful Giropay transaction, use the action Refund.  A bank transfer is then initiated which transfers the amount of the original transaction back to the consumer.

View in playground

Request


JSON gateway request

OriginalTransactionKey
Required

Transaction key of the original transaction that needs to be refunded. Please note: this is a basic parameter.

JSON

copy
{
   "Currency": "EUR",
   "AmountCredit": 1,
   "Invoice": "testinvoice 123",
   "OriginalTransactionKey": "30D459B07FD648A993ACF7D4DXXXXXX",
   "Services": {
      "ServiceList": [
         {
            "Name": "giropay",
            "Action": "Refund"
         }
      ]
   }
}

Response


JSON gateway response

customeraccountname

The customer's accountname at the bank to which the refund was performed.

CustomerIBAN

The customer's IBAN to which the refund was performed.

CustomerBIC

The international bankcode, identifying the customer's bank, belonging to the IBAN to which the refund was performed.

JSON

copy
{
   "Key": "BE6434EE6C8440B882A2A90C0XXXXX",
   "Status": {
      "Code": {
         "Code": 690,
         "Description": "Rejected"
      },
      "SubCode": {
         "Code": "S122",
         "Description": "The transaction is non-refundable."
      },
      "DateTime": "2017-07-20T10:21:57"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "giropay",
   "IsTest": true,
   "Currency": "EUR",
   "AmountCredit": 1,
   "TransactionType": "C242",
   "MutationType": 1,
   "RelatedTransactions": [
      {
         "RelationType": "refund",
         "RelatedTransactionKey": "30D459B07FD648A993ACF7D4D0BXXXXX"
      }
   ],
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "499003EB3FFC4B49B65F639C5EXXXXX"
}

Push


JSON push response

customeraccountname

The customer's accountname at the bank to which the refund was performed.

customerIBAN

The customer's IBAN to which the refund was performed.

customerBIC

The international bankcode, identifying the customer's bank, belonging to the IBAN to which the refund was performed.

JSON

copy
{
   "Transaction": {
      "Key": "BE6434EE6C8440B882A2A90C0F2XXXXX",
      "Invoice": "testinvoice 123",
      "ServiceCode": "giropay",
      "Status": {
         "Code": {
            "Code": 690,
            "Description": "Afgewezen"
         },
         "SubCode": {
            "Code": "S122",
            "Description": "De transactie kan niet worden gerefund."
         },
         "DateTime": "2017-07-20T10:21:57+02:00"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountCredit": 1,
      "TransactionType": "C242",
      "Services": null,
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 1,
      "RelatedTransactions": [
         {
            "RelationType": "refund",
            "RelatedTransactionKey": "30D459B07FD648A993ACF7D4D0XXXXX"
         }
      ],
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": null,
      "PayerHash": null,
      "PaymentKey": "499003EB3FFC4B49B65F639C5EXXXXXX"
   }
}