Additional Data Items

State management is one of the key requirements for an application developer and so ViewState technology was developed for ASP.NET. But when you are using PayPal Website Payments Standard, you are forced to let your customer leave your website for going to PayPal website and after successful or canceled payments, your customers are transferred back to your website from PayPal website. At that point, you have lost your ViewState data and the application has become stateless. In order to support a minimum level of statefulness, PayPal offers few pass through variables like ItemNumber, Custom, Invoice etc. Although you do not have complete freedom using those pass through variables as those are meant for special purposes and the values of these pass through variables are visible to your customers. Moreover, those pass through variables are of limited length. In order to overcome this limitation, we have implemented a special Collection type property named AdditionalDataItems. So, using this control, you can store as many data as you want into this property, and you will be able to access this property value in IPN handler or PDT handler. You can also store sensitive data to this property as this property value is stored in a temporary folder in your server and never sent to the client's browser.

Additional Data Items can be set both from design time (Applicable to Web Form usage only) and programmatically (both for Web Form and MVC framework). We will show both ways in the following examples.

If you want to set the some additional data items from the design time (within a Web Form scenario), please check the property AdditionalDataItems from the property browser of Visual Studio and using the design time rich collection editor, add as many items as you want to the name value collection.

But it is more practical that you would set AdditionalDataItems Collection at Run time programmatically. There are many ways to set the additional data items from code. The example we are presenting here is for a Buy Now button. But the usage is same for any other buttons (Donation, Add To Cart, Subscription etc). Even though the following example demonstrates the Click Event handler method (Web Form Scenario), the same idea can be applicable to ASP.NET MVC scenario.

Although the examples are in C#, the snippet is so simple that, we did not include VB.NET example for keeping this page short.

• The individual item for the Additional Data Item Collection is of type 'AdditionalData'. This type is just a simple class with a string property for NAME and another string property for VALUE. the AdditionalDataItems Collection will always maintain unique keys. So, if you keep adding many data with same keys, the collection will not add many items with same keys, rather, the collection will check if the Key (Name) is already there or not. If the key found, then, the collection will simply replace the old Value with the new Value. So, you wont have to worry about maintaining unique Keys.
  

• When you retrieve the value, if the Key does not exist then, null will be returned.

OK, now, we will show how you can retrieve these values in IPN_Notified event, PayPal_Returned event and Add-To-Cart Button's ReturnedForShopping event. The additional data items can be retrieved even from the IPN_Notified event of Dedicated IPN handler component 'IPNHandler' and Dedicated PayPal Return handler component 'PayPalReturnHandler'.

If you want to retrieve the data from the IPN_Notified event, please follow the following example:

If you want to retrieve the data from the PayPal_Returned event, please follow the following example:

In order to use this feature, you must have FULL Trust configuration in your ASP.NET Website. Because, the additional data items are actually stored in a temporary folder in your website, and File Writing needs FULL Trust.

Unfortunately, the 'Additional Data Items' passed by 'Add to Cart' button cannot be retrieved from IPN_Notified / PayPal_Returned event. Because, 'Add to Cart' button does not mean a single transaction, rather a set of 'Add to Cart' buttons take part in a single transaction. But IPN_Notified / PayPal_Returned event represents a single transaction. So, it can be very confusing to use Additional Data Items in IPN/PayPal Return event generated by 'Add to Cart' button. So, the current version does not support using 'Additional data items' in this scenario. But our future version may support a better solution for this scenario if we receive many requests from our users.


Temporary Folder:

By default, the temporary folder used is "~/App_Data/" because this folder usually has WRITE permission. So if you have App_Data folder ready with WRITE permission, you can use this 'Additional Data Items' feature out of the box. But if you want to use a different folder, you can do so. Simply locate the property 'InternalSettings.TemporaryFolder' from the Property Browser and set the relative path to any folder that got WRITE permission.

If you change this temporary folder and if you retrieve the value from IPNHandler Component's IPN_Notified event which is hosted in a dedicated IPN handler page, then, you should remember to set this temporary folder property of that Dedicated IPNHandler component otherwise, the component wont know where the Additional Data Items are stored.

In the same way, if you want to retrieve the additional data from the PayPal_Returned event of the PayPalReturn Handler component hosted in a dedicated page for handling the PayPal Return Scenario, set the Temporary Folder property as shown here:

What about deleting temporary files ?:

Now, it is time to know how the temporary files are maintained ? will they get accumulated continuously ? If so, that will be bad. We know about it and so, the control is capable of taking care of this maintenance issue. It has a property named 'InternalSettings.DeleteAdditionalDataTempFilesInHours'. By default, it's value is '1'. That means, the control will check the temporary folder in every new session and check the time-stamp of the temporary files. If any file is more than 1 hour old, then, DELETE that file. So, of course, the control will not delete the temporary file EXACTLY within 1 hour. Rather this '1 hour' is the minimum duration that a temporary file can live. If the page hosting the PayPal control is loaded after 2 hours since the temporary file is created, then, that temporary file will be deleted by 2 hours. Moreover, once the control checks the temporary folder, it will not check the temporary folder any more in the same session. The control will check the temporary folder again if the page hosting the PayPal control is loaded again after the Session is expired. So, obviously you can see that this attitude is very LAZY rather than aggressive. Why ? Because, File Read / WRITE operation is a time consuming operation which affects the performance of your website. If you have more than one PayPal control in your page, then the performance cost is increased. So, in order to favor the performance, the control behaves Lazy to delete those temporary files. If you check your temporary folder and see many temporary files, do not worry, the control is aware about this accumulated number and it will delete those files in right time.

Wait a minute. If you delete the temporary file for a specific transaction, then, when IPN_Notified event is fired later for some event (eCheck cleared, Subscription Canceled, Subscription Payment etc) the control wont find the 'Additional Data Item' for that transaction and if your IPN_Notified event handler logic depends on 'Additional Data Items' then your logic wont success in that case. So, what can you do ? You may set the 'InternalSettings.DeleteAdditionalDataTempFilesInHours' to a higher number to allow few weeks depending on your scenario. For example, if you are using only Buy Now button, then, when eCheck is cleared, IPN will be submitted. eCheck is cleared usually 5-7 business days. So, you may set the 'InternalSettings.DeleteAdditionalDataTempFilesInHours' to enough hours that can hold 2-3 weeks. If you are using Subscription button and if you depend on Additional Data Items, then, temporary file deleting logic should be implemented more carefully. You should allow enough time so that all subscription events can be covered by that time.

If you do not want to let the control delete the temp files by itself, then, simply set 'InternalSettings.DeleteAdditionalDataTempFilesInHours' = -1. You may set this value to -1 if you plan to delete the temp files manually once a while or if you have your own maintenance script that deletes the temp folder periodically.