Handling Payment Data Transfer (PDT) & Return

If you are not familiar with How PayPal IPN and PDT works, please visit this page for learning about Post Payment Notifications  before proceed to this documentation.

1. Cancel to proceed and optionally return to your website.
   
2. Proceed and complete the payment and optionally return to your website. Your customer will be transferred to your website automatically (within 10 seconds) if he/she has PayPal account.

So, whenever your customer is transferred back to your website from PayPal website, you can execute post payment business logic on your website. This control is capable of firing an event named "PayPal_Returned" whenever your customer is returned to your website from PayPal website. The event argument object of this event carries the information about:

• Whether the payment was cancelled or completed,
  
• If completed whether PDT (Payment Data Transfer) transaction data available with this return or not.
  
• If a valid PDT authentication token was used, all PDT data is available through the event argument class as an organized collection of composite properties and collection type properties.

What is Payment Data Transfer (PDT) ?

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 control, you must get your PDT Authentication Token and update the control with this token in Design Mode from the Smart Tag Wizard a shown below:

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.

The Payment Button Controls (BuyNow Button, Donation Button, Subscription Button, Upload Complete Cart Button but NOT the Add to Cart Button) are designed such a way so that, PayPal Return can be handled like handling an event of a standard asp.net control. So, if you place this control on your web form for BuyNow Button, Donation Button, or other Payment Button controls, then you can use the same aspx page to place your PayPal Return/PDT handling logic and this design pattern gives you the flexibility to use a single aspx page for managing all of your eCommerce related business logics. In order to start, simply attach an event handler method to the PayPal_Returned event of your Payment Button control as shown in the following figure.

The "PayPal_Returned" is the event which is fired as soon as PayPal transfers your customer to your website. This control automatically generates the PayPal variable "return" and "cancel_return" so that PayPal knows that the same page is the "PayPal Return - Thank you" page.

There are cases when you may not want to use the same Button hosting page to be your PayPal Returned Handler page. Specially when you are using ADD TO CART Button you must use a dedicated page for handling PayPal Return. In order to point a different page to be your PayPal Returned handler, please Click Here  to learn about Handling PayPal Return from a dedicated page .

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).

As you are not sure weather your user will close the browser before returning to your website or not, you should use IPN (and not the PDT) to generate any license key, sending email receipts, storing the transaction information in your database etc and use PayPal_Returned event to convey the message to your customer about the transaction like "Thank you for the payment, you should receive an email with your License Key" etc.. As generating email receipt, license keys etc is the most important part of post payment actions, you make sure that this tasks are done without the control of your customer and handling IPN is the way to do this. Usually IPN_Notified event is fired as soon as the payment transaction is completed while your customer is in the PayPal website. Once your customer returns to your website from PayPal website, PayPal_Returned  event is fired. So, we can assume that, any stored information (in your database) which was stored in the IPN session is ready to be retrieved (from your database) in the PayPal_Returned event. So, in PayPal_Returned event, you can show your customer a summary of tasks done in IPN_Notified event.

When the "PayPal_Returned" event is fired and if a valid value for "PDT_Authentication_Token", all transaction information becomes available as strongly typed objects (categorized collection of composite properties and collections) through the Event Argument Class.

Please note: when you are using SpiceLogic PayPal control, you are not limited to receive only PayPal provided transaction data. You can pass unlimited data from your Payment Button which will not be even sent to PayPal, rather it will be saved in your server and when PayPal_Returned event is fired, you will be able to retrieve those data. Please visit the page for Passing Additional Data Items  for more details.

Practicing Mediator Design Pattern:

If you have many Payment Buttons (i.e. BuyNow button, Donation Button etc..) in a same page, then you can use a common PayPal_Returned event handler for all of the button's PayPal_Returned Event. But, if you have many Payment Buttons in your web applications where those are not in the same page and if you want to centralize all of your PayPal return (PDT) related logic in a single method, then you should Handle PayPal Return from a dedicated page .

How to Test PayPal_Returned event as well as PDT ? Is it possible to test the PayPal_Returned event and PDT feature right from my localhost (or Desktop Computer) ?

YES, you CAN test PayPal_Returned event with PDT right from your development environment. Even if your testing page's url is something like http://localhost/xxxxxx.aspx , doesnot matter. So, if you handle the PayPal_Returned event and attach an event handler method to this event, you will be able to simulate a transaction (by running your page, clicking the payment button and you will be taken to PayPal Website, finish the transaction and you will be returned back to your website from PayPal website) and as soon as you are sent back to your webpage, you will see that the PayPal_Returned event fired.

Unlike the limitation about testing IPN right from localhost, there is no such problem about testing PDT from localhost. So, you wont even need to upload your testing pages to your production server just for testing.

How to Debug PDT ?

As PayPal_Returned event is a synchronous visual event, you can easily debug this event handler method same like you debug any Click event handler method of any Button Control. You can set a breakpoint on your PayPal_Returned event handler method and step through the lines from Visual Studio Debugger. The PayPal_Returned Event argument object's PDT.ToString() method is overriden and it contains a set of useful information like what was the raw string posted to your website as PDT, how long it took to complete the notification synchronization and object building, which string was sent back to PayPal (or PDT sender) server. Here is a sample ToString() value returned by e.PDT.ToString() from the PayPal_Returned Event Argument Object of a BuyNow button.

PDT Status (Enumerated value) : SUCCESS Error message (IF) : Time required for notification synchronization : 788ms Time required for building the event argument object : 0ms ======= Sent Data for Notification Sync ======== cmd=_notify-synch tx=323AQ32259SA54FG2F at=fZ54345pd0uqg87567436dDSAF42LsdfaAFAQ326ozQ6Hl ------------------------------------------------ ======= Original Raw data received from PDT ==== SUCCESS transaction_subject=Vocabulary+Builder+for+SAT+ACT+GRE+GMAT+%26+LSAT+1.8.0.2 payment_date=11%3A59%3A13+Feb+11%2C+2010+PST txn_type=web_accept last_name=Mike residence_country=CA item_name=Vocabulary+Builder+for+SAT+ACT+GRE+GMAT+%26+LSAT+1.8.0.2 payment_gross=0.01 mc_currency=USD business=xxxxxxxx%40xxxxxxxx.com payment_type=instant protection_eligibility=Ineligible payer_status=verified tax=0.00 payer_email=xxxx%40xxxxxx.ca txn_id=323AQ32259SA54FG2F quantity=1 receiver_email=spqwgic%40xxx.com first_name=Ensar invoice=SE7B36 payer_id=GH2441L86A receiver_id=N45SW120PE item_number=SpiceLogicVocab handling_amount=0.00 payment_status=Completed payment_fee=0.01 mc_fee=0.01 shipping=0.00 mc_gross=0.01 custom= charset=windows-1252 ------------------------------------------------ ===== Decoded data received from PDT =========== transaction_subject=Vocabulary Builder for SAT ACT GRE GMAT & LSAT 1.8.0.2 payment_date=11:59:13 Feb 11, 2010 PST txn_type=web_accept last_name=Mike residence_country=CA item_name=Vocabulary Builder for SAT ACT GRE GMAT & LSAT 1.8.0.2 payment_gross=0.01 mc_currency=USD business=xxxxxxxx@xxxxxxxx.com payment_type=instant protection_eligibility=Ineligible payer_status=verified tax=0.00 payer_email=xxxx@xxxxxx.ca txn_id=323AQ32259SA54FG2F quantity=1 receiver_email=spqwgic@xxx.com first_name=Ensar invoice=SE7B36 payer_id=GH2441L86A receiver_id=N45SW120PE item_number=SpiceLogicVocab handling_amount=0.00 payment_status=Completed payment_fee=0.01 mc_fee=0.01 shipping=0.00 mc_gross=0.01 custom= ------------------------------------------------

How to get this string ? Ok, handle the PayPal_Returned event and in your event handler method, assign the value of e.PDT.ToString() to a string type variable. Then, you may email that string value to yourself or show that string to a TextBox in the same web page. The following snippet shows the usage:

You can also get the data in parts by dedicated properties. For example, e.PDT.Status will give you the enumerated status code. e.PDT.SentDataForNotificationSync will give you the data sent to PDT sender for notification synchronization. If you get FAIL status, you should check this property value and see, if your PDT authentication token was correctly sent to PayPal or not. Your PDT Authentication token will sent as at="...". So, if you see that the value of 'at' in e.PDT.SentDataForNotificationSync is Empty, then, it is possible that you did not upload your modified web.config file to your production server just after you provided the PDT Authentication Token to your control. As we mentioned earlier that, PDT authentication token is saved in your Web.config file and as soon as you set the PDT Token to your Payment Button using the Design Time wizard, you should remember to upload your web.config file to your production server.

In order to access the specific variable string data (for both IPN & PDT) received by PayPal, you can use a NameValueCollection type event argument property named "PostedData". For example, you can get the Payment date as strongly typed object like this : DateTime paymentDate = e.PaymentDateTime; but if you want to see what was the actual string for "payment_date" variable posted by PayPal in case you are suspecting that you are getting wrong data. So the following snippet will give you the exact string for the PayPal variable "payment_date"

string PayPal_Posted_DateTime_String = e.PostedData["payment_date"];

Also, if you want to get a value of a new PDT data which is not available from this control's PayPal_Returned event argument object (it is highly unlikely unless the ipn version is updated very recently by PayPal and our development team took some time to synchronize our control with that ipn version. Also we may find some undocumented and unimportant variables introduced recently which is not included in the PayPal_Returned event argument object. For example, we did not find 'protection_eligibility' variable important to include to the type safe list of properties as it is not even well documented by PayPal.), you can get that value from e.PostedData NameValueCollection like this:

string ProtectionEligibility = e.PostedData["protection_eligibility"];

A special note for Subscription Button Users

PDT Status will be returned as FAILED when using a free trial. Because, PDT returns information when a payment has been made.  Since the trial is free, it will not return any information.  If you are needing information back through the use of PDT you would need have the trial for atleast 0.01, or use IPN  to do what you are doing with the returned PDT information as this information will be returned regardless.

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 ?