Prerequisite for this article: You should have the basic idea of handling PayPal return from this page: handling PDT & Return .

Every payment buttons except ADD To Cart button (i.e. BuyNow Button, Donation Button etc) come with the event PayPal_Returned. If you handle that event of those buttons, then you do not need to use PayPalReturnHandler Component at all.

The PayPalReturnHandler component is designed for those scenario where you want to use different pages for hosting your Payment Button (i.e. BuyNow Button) and PayPal return logics (i.e. PDT, "thank you" message, cacelled return message etc.)

In order to associate a PayPalReturnHandler component with a PayPal Return event caused by a Payment Button (i.e. BuyNow Button, Donation Button etc..) that is hosted in a different page, you need to follow the following steps:

(The example is shown for a BuyNow button, but the same procedure works for all other button controls)

1. In the design mode of a BuyNow Button, open the smart tag wizard and go to the tab named "Step 4 (Payment Return/PDt) as shown in the following screen shot. Check the 2nd option and provide the relative path of the dedicated PayPal return handler files.

2. Once you have done this, you know that, "~/Products/myCompletedPaymentReturnURL.aspx" is the page which will be called by PayPal after a successful payment action. So, you should place an instance of the PayPalReturnHandler component in this web form. Please note, we did not use a different page for Cancelled payment return url as it is more efficient to use a single page for both "completed payment url" and "cancelled payment url". You can differentiate these two action by a special query string "slPPCStatus=cancel". Why did we use this query string ? Because, this querystring can be recognized by the PayPalReturnHandler as a cancelled payment and then it will generate strongly typed property to notify you that the payment was cancelled. We will explain this after few paragraphs.

3. Now, create an aspx page named "myCompletedPaymentReturnURL.aspx" and place an instance of the PayPalReturnHandler component as follows:

The "PayPal_Returned" event of the PayPalReturnHandler component will be fired as soon as the page is loaded (returned from PayPal). You should place only one instance of this control in an aspx page. Because, if you place multiple instances, all instance's PayPal_Returned event will be fired as soon as the page is loaded which is not an expected matter at all.

4. Now, once you have placed an instance of this component into your webform, attach an event handler method for the event "PayPal_Returned". This event handler method is the method which will contain your business logics.

Now, do you remember that we used a special query string "slPPCStatus=cancel" appended to the "~/Products/myCompletedPaymentReturnURL.aspx" ? Please note the above snippet we used for the PayPalReturnHandler1_PayPal_Returned event handler method. In that snippet, we used a statement if(e.IsPaymentCancelled) { .. }. You may ask, how the component knows if the payment was cancelled or not, right ?. Ok, the component check for the special query string "slPPCStatus=cancel" and if it finds this querystring, it sets e.IsPaymentCancelled = true.

5. Payment Data Transfer:  What is Payment Data Transfer ?

Payment Data Transfer (PDT) is a secure method to retrieve the details about a PayPal transaction so that you can display them to your customer who are redirected back to your site upon payment completion. In order to use PDT, you must activate PDT  from your PayPal profile, because it is disabled by default. By using PDT, your customer can instantly view a confirmation message with the details of the transaction.

PDT Authentication Token:

When you activate PDT, you will get an identification token named "PDT authentication token" a string value that identifies your account to PayPal. If you want to handle PDT using this component, you must provide this token to the component. The following screenshot shows how you can do that in Design Time.

Please note: this value is stored in the Web.Config file, so please remember to upload the Web.Config file after you change the PDT Authentication Token value in this component. If the component does not find any PDT Token, then e.PDT.Status will be set as "NotHandlingPDT" and no transaction related data will be availale except the transaction id.

NB: It is possible to miss a PDT notification if the user closes the browser before the redirection is complete. For this reason, it is strongly recommended that you also handle Instant Payment Notification (IPN).

It is the best practice to use IPN_Notified event for processing your post payment logics like checking if the payment was valid then deliver the digital product by email, send email for receipts etc. Because, either your customer closes the browser after the payment or not, the IPN_Notified even will always be fired because, IPN is an asynchronous process invoked by PayPal. Then you should use PayPal_Returned event to convey the message about the payment to your customer like "Thank you for the payment, you should receive an email with your License Key" etc. Also within the PayPal_Returned event handler, you can check your database if the IPN_Notified event already generated the License Key or delivered the digital product by email or not. If you find that, it is already done, then you can also convey the message like "We have already generated the License Key for you, here it is ..." to your customer.

Code Example:

Communicating with the server

Please Wait..............................

Hosting Trust Level issue:

Explanation: 

When PayPal_Returned event is fired, the control reads the transaction token from the query string variable "tx" and retrieve transaction details from PayPal by constructing HTTPS POST to PayPal. This is called notification synchronization. In order to post to a website, the component needs to call one of the method from the WebClient class library available from System.Net namespace.

Now, executing WebClient class methods requires Full Trust configuration in the hosting and if you do not have full trust configuration, then not only using this control, but also you cannot use the PDT feature by even manually coding by yourself or using any other control at all.

But, but, if you got any solution about calling a website from the web application in medium trust level, simply let us know and we will modify our control to make it compatible with medium trust hosting and offer you a FREE developer license for this control.

Still Confused ?