Menu

Giropay

Note: To learn about the features of Giropay, there's an overviewhere

How to integrate Giropay payments:

Direct payment request

Submitting a Direct request is a two-step process:

  1. You send us a payment request. We respond to your payment request and provide you with a unique URL.
  2. You use the URL we supply to redirect your shopper.

Themandatoryandrecommendeddata are shown below.

Copied!
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="YOUR_MERCHANT CODE" version="1.4">
  <submit>
    <order orderCode="YOUR_ORDER_CODE"><!--Use a unique order code each time-->
      <description>test order</description>
      <amount exponent="2" currencyCode="EUR" value="100" />
      <paymentDetails>
        <GIROPAY-SSL>
          <successURL>http://www.worldpay.com/?success</successURL>
          <failureURL>http://www.worldpay.com/?failure</failureURL>
          <cancelURL>http://www.worldpay.com/?cancel</cancelURL>
          <swiftCode>PBNKDEFF</swiftCode>
        </GIROPAY-SSL>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
      </shopper>
    </order>
  </submit>
</paymentService>

Responses

We respond to your payment request with either:

  • A confirmation that your request has been successfully received, along with a URL for your to redirect your shopper.
  • An exception that shows your request has not been successfully received, along with an appropriate exception message.

Successful response

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="AZAMTESTCGM1">
  <reply>
    <orderStatus orderCode="jsxml3473709078">
      <reference id="5740361394">https://giropay.postbank.de/ftg/a/go/0rv350wgc8j0k0wvrjhssxqo;jsessionid=80747F843CE1549DDE4856DF2B380B0B.sf-ftgprodapp02tom13</reference>
    </orderStatus>
  </reply>
</paymentService>

Exception response

In this example, the merchant has submitted an invalid BIC in the payment request, and Wordpay respond with an appropriate exception.

Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService
PUBLIC '-//Worldpay//DTD Worldpay PaymentService v1//EN'
'http://dtd.worldpay.com/paymentService_v1.dtd'>
<paymentService merchantCode="AZAMTESTCGM1" version="1.4">
  <reply>
    <orderStatus orderCode="jsxml3221074380">
      <error code="7">
        <![CDATA[invalid BIC in Senderaccount:PBNKEFF]]>
      </error>
    </orderStatus>
  </reply>
</paymentService>

Other types of exception include:

  • Our provider’s system is undergoing maintenance (very rare)
  • The requested bank is currently offline
  • The bank is blacklisted
  • An internal error has occurred that prevents the BIC being validated

Mandatory data

Parameter nameDescription
shopperEmailAddressThe email address of the shopper
successURLThe result URL that redirects the shopper for an authorised transaction.
failureURLThe result URL used to redirect the shopper in certain scenarios such as:
  • The PSP refuses the payment
  • The shopper cancels the payment on the giropay payment pages
    cancelURLThe result URL used if the shopper cancels the payment on Worldpay payment pages (redirect model only).

    Parameter nameDescription
    swiftCodeThe BIC/Swift code of the shopper’s bank. This can be either:
    • A valid BIC (Business Identifier Code)
    • Null

    If null, then the system asks the shopper to select their bank.

    You can decide whether you collect the shopper’s bank yourself, or whether you want our provider to collect it for you. Reasons to collect the shopper's bank yourself include:
    • There will be fewer steps for the shopper to complete once they leave your website.
    • You maintain control of the shopper for a greater part of the shopper journey


    Reasons to let our provider collect the shopper's bank for you include:
    • You do not need to maintain an up-to-date list of valid banks.

    If you provide an invalid BIC, we return an error in response to your API call.

    Hosted payment request

    To redirect the shopper directly to the Giropay payment pages append the below string to the end of the redirect URL provided in the XML response from Worldpay:

    &country=DE&language=en&preferredPaymentMethod=GIROPAY-SSL

    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService PUBLIC '-//Worldpay//DTD Worldpay PaymentService v1//EN'
    'http://dtd.worldpay.com/paymentService_v1.dtd'>
      <paymentService merchantCode="YOURMERCHANTCODE" version="1.4">
        <submit>
          <order orderCode="jsxml3511273605"><!--Use a unique order code each time-->
            <description>Test order</description>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <orderContent/>
            <paymentMethodMask>
              <include code="ALL"/>
            </paymentMethodMask>
            <shopper>
              <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
            </shopper>
            <statementNarrative>MERCHANT STATEMENT NARRATIVE</statementNarrative>
          </order>
        </submit>
      </paymentService>

    Mandatory data

    You do not have to submit any mandatory data for an XML order request in the Hosted model specific to a Giropay payment.

    <Null>

    Payment outcomes

    Successful payment

    Shopper pays
    Event 1The shopper successfully completes a payment for EUR 1.00 on the Giropay payment pages.
    BehaviourThe successURL is returned, along with the following appended Worldpay parameters:
    • orderKey
    • paymentStatus
    • paymentAmount
    • paymentCurrency
    • mac
    URLsuccessURL
    URL Example:http://www.worldpay.com/?success&orderKey=ADMINCODE^MERCHANTCODE^GiropayTestOrder&paymentStatus=AUTHORISED&paymentAmount=100&paymentCurrency=EUR&mac=ec333c3a4d698f1f5a3f97d590ac40c4
    Payment StatusPayment status changes to SENT_FOR_AUTHORISATION and then to AUTHORISED
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService PUBLIC '-//Worldpay//DTD Worldpay PaymentService v1//EN'
    'http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="MERCHANTCODE" version="1.4">
      <notify>
        <orderStatusEvent orderCode="GiropayTestOrder">
          <payment>
            <paymentMethod>GIROPAY-SSL</paymentMethod>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent>AUTHORISED</lastEvent>
            <balance accountType="IN_PROCESS_AUTHORISED">
              <amount currencyCode="EUR" ebitCreditIndicator="credit" exponent="2" value="100"/>
            </balance>
            <riskScore value="0"/>
          </payment>
          <journal journalType="AUTHORISED">
            <bookingDate>
              <date dayOfMonth="17" month="01" year="2013"/>
            </bookingDate>
            <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="691">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            </accountTx>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>
    Payment captured
    Event 2The payment is captured in WPG.
    BehaviourThe automatic capture job runs in WPG to automatically capture the payment
    URLNo URL is returned to the shopper because the shopper journey is already complete
    URL Example:Not applicable
    Payment StatusPayment status changes to CAPTURED
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService
    PUBLIC '-//Worldpay//DTD Worldpay PaymentService v1//EN'
    'http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="MERCHANTCODE" version="1.4">
      <notify>
        <orderStatusEvent orderCode="GiropayTestOrder">
          <payment>
            <paymentMethod>GIROPAY-SSL</paymentMethod>
            <amount currencyCode="EUR" ebitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent>CAPTURED</lastEvent>
            <balance accountType="IN_PROCESS_CAPTURED">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            </balance>
            <riskScore value="0"/>
          </payment>
          <journal journalType="CAPTURED">
            <bookingDate>
              <date dayOfMonth="17" month="01" year="2013"/>
            </bookingDate>
            <accountTx accountType="IN_PROCESS_CAPTURED" batchId="830">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            </accountTx>
            <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="1698">
              <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="100"/>
            </accountTx>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>
    Payment settled
    Event 3The payment is settled internally in the Worldpay system.
    BehaviourThe automatic capture job runs in WPG to automatically capture the payment. The payment is successfully settled internally in WPG.

    The Merchants settlement currency for the example Merchant Code below is EUR.
    URLNo URL is returned to the shopper because the shopper journey is already complete.
    URL exampleN/A
    Payment statusPayment status changes to SETTLED
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService
    PUBLIC '-//Worldpay//DTD Worldpay PaymentService v1//EN'
    'http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="MERCHANTCODE" version="1.4">
      <notify>
        <orderStatusEvent orderCode="GiropayTestOrder">
          <payment>
            <paymentMethod> GIROPAY-SSL </paymentMethod>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent> SETTLED </lastEvent>
            <balance accountType="SETTLED_BIBIT_COMMISSION">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="14"/>
            </balance>
            <balance accountType="SETTLED_BIBIT_NET">
              <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="14"/>
            </balance>
            <riskScore value="0"/>
          </payment>
          <journal journalType="SETTLED">
            <bookingDate>
              <date dayOfMonth="21" month="01" year="2013"/>
            </bookingDate>
            <accountTx accountType="SETTLED_BIBIT_COMMISSION">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="14"/>
            </accountTx>
            <accountTx accountType="SETTLED_BIBIT_NET" batchId="744">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="86"/>
            </accountTx>
            <accountTx accountType="IN_PROCESS_CAPTURED" batchId="830">
              <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="100"/>
            </accountTx>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>

    Exceptions and cancellations

    Shopper cancels (bank selector)
    Event 1The shopper clicks cancel on the bank selector page (if the merchant has not specified a BIC).
    The shopper is shown a message confirming that they have cancelled the payment, and they are redirected back to the merchant’s failure URL.
    Other use cases that will use the failure URL include:
    • The shopper’s bank went offline during the transaction
    • The bank account was not valid (i.e. the bank itself was valid, but the type of account used by the shopper was not)
    • The bank returned an unrecognised status
    • The transaction was not authorised for some other reason
    URLFailure URL
    URL examplehttp://www.worldpay.com/?failure&orderKey=AZAMTESTCG^AZAMTESTCGM1^jsxml3713592470&paymentStatus=REFUSED&paymentAmount=100&paymentCurrency=EUR&mac=306b8d50bab2683658108965bd37b87b
    Payment Status:Payment status changes to SENT_FOR_AUTHORISATION and then immediately to REFUSED.
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService
    PUBLIC '-//Worldpay//DTD Worldpay PaymentService v1//EN'
    'http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="AZAMTESTCGM1" version="1.4">
      <notify>
        <orderStatusEvent orderCode="jsxml3713592470">
          <payment>
            <paymentMethod>GIROPAY-SSL</paymentMethod>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent>REFUSED</lastEvent>
            <riskScore value="0"/>
          </payment>
          <journal journalType="REFUSED">
            <bookingDate>
              <date dayOfMonth="12" month="10" year="2016"/>
           </bookingDate>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>
    Shopper cancels (bank)
    Event 2The shopper clicks cancel on the bank’s landing page.

    This behaviour can vary by bank.

    Some banks by exhibit the behaviour observed in Event 1.
    BehaviourThe shopper is redirected to your cancel URL.
    URLCancel URL
    URL examplehttp://www.worldpay.com/?cancel
    Payment Status:No payment is created.
    Notification exampleN/A

    Refunds

    Refund request
    Event 1The merchant requests a refund of 1.00 EUR from the Merchant Interface.
    BehaviourThe merchant requests a refund of the settled payment on the MI. The Merchants settlement currency in the example below is GBP.
    URLN/A
    URL exampleN/A
    Payment Status:Changes to SENT_FOR_REFUND.
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService
    PUBLIC '-//Worldpay//DTD WorldPay PaymentService v1//EN'
    'http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="MERCHANTCODE" version="1.4">
      <notify>
        <orderStatusEvent orderCode="GiropayTestOrder">
          <payment>
            <paymentMethod> GIROPAY-SSL </paymentMethod>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent> SENT_FOR_REFUND </lastEvent>
            <riskScore value="0"/>
          </payment>
          <journal journalType="SENT_FOR_REFUND">
            <bookingDate>
              <date dayOfMonth="17" month="01" year="2013"/>
            </bookingDate>
            <accountTx accountType="IN_PROCESS_CAPTURED" batchId="830">
              <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="100"/>
            </accountTx>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>
    Refund sent to Giropay
    Event 2The refund request is successfully sent to Giropay.
    BehaviourThe Worldpay Payment Service successfully submits the refund request to Giropay. The Merchants settlement currency in the below example is GBP.

    The Worldpay settlement currency in the below example is USD.
    URLN/A
    URL exampleN/A
    Payment Status:Changes to REFUNDED.
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentService PUBLIC '-//WorldPay//DTD WorldPay PaymentService v1//EN''http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="MERCHANTCODE" version="1.4">
      <notify>
        <orderStatusEvent orderCode="GiropayTestOrder">
          <payment>
            <paymentMethod> GIROPAY-SSL </paymentMethod>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent> REFUNDED </lastEvent>
            <balance accountType="SETTLED_BIBIT_NET">
              <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="100"/>
            </balance>
            <balance accountType="IN_PROCESS_CAPTURED">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            </balance>
            <riskScore value="0"/>
          </payment>
          <journal description="Refund for order: GiropayTestOrder" journalType="REFUNDED">
            <bookingDate>
              <date dayOfMonth="17" month="01" year="2013"/>
            </bookingDate>
            <accountTx accountType="SETTLED_BIBIT_NET" batchId="743">
              <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="100"/>
            </accountTx>
            <accountTx accountType="IN_PROCESS_CAPTURED" batchId="830">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            </accountTx>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>
    Refund fails
    Event 3The refund fails.
    BehaviourThe Worldpay Payment Service receives confirmation that the payment has not been successfully sent to the shopper’s Giropay account.
    URLN/A
    URL exampleN/A
    Payment Status:Changes to REFUND_FAILED
    Copied!
    <?xml version="1.0" ?>
    <!DOCTYPE paymentServicePUBLIC '-//WorldPay//DTD WorldPay PaymentService v1//EN''http://dtd.worldpay.com/paymentService_v1.dtd'>
    <paymentService merchantCode="MERCHANTCODE" version="1.4">
      <notify>
        <orderStatusEvent orderCode="GiropayTestOrder">
          <payment>
            <paymentMethod> GIROPAY-SSL </paymentMethod>
            <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            <lastEvent> REFUND_FAILED </lastEvent>
            <balance accountType="SETTLED_BIBIT_COMMISSION">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="14"/>
            </balance>
            <balance accountType="SETTLED_BIBIT_NET">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="86"/>
            </balance>
             <riskScore value="0"/>
          </payment>
          <journal description="Refund Failed for order: GiropayTestOrder" journalType="REFUND_FAILED">
            <bookingDate>
              <date dayOfMonth="23" month="01" year="2013"/>
            </bookingDate>
            <accountTx accountType="SETTLED_BIBIT_NET" batchId="744">
              <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="100"/>
            </accountTx>
          </journal>
        </orderStatusEvent>
      </notify>
    </paymentService>