Integrating giropay with Express Checkout

You must modify your Express Checkout implementation to use giropay, a common German funding source.

giropay Page Flows

If you accept giropay, you must redirect to the giropay website to collect the funds after completing the Express Checkout transaction.

When your buyer selects giropay as a funding source during the Express Checkout flow, you redirect the buyer to a static PayPal URL after your order review page. PayPal then redirects the buyer to the giropay website to push the funds to the merchant. After the giropay payment is successfully completed, the transaction is confirmed.

If the giropay payment fails or the buyer cancels, PayPal provides the necessary details for an electronic funds transfer (EFT) so that the buyer can complete the transaction by pushing funds from his or her bank account. If your PayPal account profile blocks non-instant payments, the transaction is canceled.

giropay Payment Page Flow

The following diagram illustrates the flow of a successful giropay payment:



Canceled or Unsuccessful giropay Payment Page Flow

If the giropay payment fails for any reason, such as insufficient funds or the buyer cancels, PayPal provides details to the buyer to do a bank transfer from their bank account. This transaction will remain pending until PayPal receives the funds, at which time the transaction is complete.

If you have disabled non-instant funding transactions for your PayPal account, the transaction is canceled and PayPal redirects the buyer to your Order Cancel page.

After the bank transfer flow completes, the transaction is pending until the buyer pushes the funds to PayPal.

If the buyer cancels during the PayPal payment in the bank transfer flow, your Order Cancel page is displayed.

giropay Integration

If you offer the giropay payment option, you must take additional steps to integrate with the Express Checkout flow.

Initiate the Flow with SetExpressCheckout

To support giropay payments, pass the following three URLs as part of the SetExpressCheckout request:

NVP Field Description
GIROPAYSUCCESSURL The URL on the merchant site to redirect to after a successful giropay payment.
GIROPAYCANCELURL The URL on the merchant site to redirect to after a giropay or bank transfer payment is cancelled or fails.
BANKTXNPENDINGURL The URL on the merchant site to transfer to after a bank transfer payment.

These URLs tell PayPal where to redirect the buyer based on the success or failure of each type of payment transaction. See the PayPal Name-Value Pair Developer Guide and Reference for more information.

Redirect the Buyer to PayPal

After selecting a funding source on PayPal, the buyer is redirected back to your website, as in the regular Express Checkout flow. There is one additional field, REDIRECTREQUIRED, returned in the response from both GetExpressCheckoutDetails and DoExpressCheckoutPayment:

NVP Field Description
REDIRECTREQUIRED Flag to indicate whether you need to redirect the buyer to back to PayPal

If the value of this field is true, redirect the buyer from your Order Review page to https://www.paypal.com/cgi-bin/webscr?cmd=_complete-express-checkout&token=<value_from_SetExpressCheckoutResponse>. PayPal then redirects the buyer from this redirect page to the necessary page for the selected funding source.

The GetExpressCheckoutDetails response contains the REDIRECTREQUIRED field, which lets you know if you need to redirect the buyer after your Order Review page. You can use this value to inform the buyer on your Order Review page that they will be sent to the giropay website to complete the order.

Complete the Transaction

Corresponding to the three fields passed to SetExpressCheckout, you must add the following three additional pages to your website:

Your website's pages Description
Order Completion The page specified in GIROPAYSUCCESSURL to which PayPal redirects the buyer after a successful giropay payment.
Order Cancelation The page specified in GIROPAYCANCELURL to which PayPal redirects the buyer after a giropay or bank transfer payment is canceled or fails.
Order Pending The page specified in BANKTXNPENDINGURL to which PayPal redirects the buyer after a bank transfer payment.

Receive Transaction Status Notification

After PayPal redirects the buyer to giropay, you receive transaction status information in the following ways:

  • IPN Notification
  • Email (only for successful giropay or bank transfer transactions)
  • PayPal Account Overview
  • PayPal reports