This page explains the usage and facts about the Upload-Complete-Cart button Web Form Server Control. If you intend to use Upload-Complete-Cart button within your ASP.NET MVC project, please visit this page.
Instead of relying on the PayPal Shopping Cart, many merchants use third party shopping carts that integrate with PayPal. This chapter describes how developers of third party carts integrate with PayPal using ASP.NET PayPal Control for Website Payments Standard.
There are two ways to integrate your third party shopping cart with PayPal and Website Payments Standard:
- Pass the details of the individual items. You can do that using 'Upload Complete Cart' button. In this approach, you can track individual cart items from IPN_Notified / PayPal_Returned event.
- Pass the aggregate amount of the total cart payment, rather than the individual item details. If you follow this approach, then a Buy Now button can serve this purpose. But following this approach, you wont be able to track the individual cart items from IPN_Notified / PayPal_Returned event.
|- The Checkout Experience
- Getting Started
|- Set Properties Programmatically
- Click Event and Post Back
|- Handling Instant Payment Notification (IPN)
- Handling PayPal Return / PDT
Drag and drop an instance of the Upload Complete Cart Button control from your Visual Studio Toolbox to your web form as shown below:
The first property of this control that you need to set is your Business Email Address or Merchant ID of your Merchant Account. If you are testing in Sand Box, then, this is the account which you created as 'Test Merchant Account' as explained in the Sand Box preparation chapter. Please do not get confused with the Developer Central Login account with the Test Merchant Account. Merchant ID is an alternative to using your Email address. It is better not to expose your business email address in order to protect your Email In-box from Spams. You can set either Business Email or Merchant ID from the Smart Tag or from the Property Editor. In order to get your Merchant ID, log in to your PayPal account. If you are testing in Sand-box, then, log in to your Developer Central Account, then log in to your Merchant Test Account from https://www.sandbox.paypal.com/. Click 'Profile' Menu, then, your Merchant ID will be shown up as shown in the following screen shot.
Set the merchant ID as shown here:
Now, you may populate the Collection type property named PayPalCartItems either in Design Mode or Run Mode. It is more practical that you programmatically populate this property in Run Mode based on the present cart items selected by your customer in your third party shopping cart. Design Mode population is useful if you want to test and debug your web application. For example, please see the following screen shot, you see that PayPalCartItems collection property has rich design time support where you can populate the property with some values and Run your website, clicks the button and see how the cart items are passed to PayPal shopping cart.
Furthermore, you may choose to set the visual styles and PayPal page behaviors for the 'Upload Complete Cart' button. Just click the button "Next" shown in the wizard and you will be taken to configure the display page as shown in the following screen shot.
Please note: If your account is not upgraded to a Premier or Business account, then, you will not see any affect of these styling properties for PayPal page. For example, if you set a header image URL, you will not see that image when you are taken to PayPal website due to a click on the 'Upload Complete Cart' button. In that case, you will see your email address as the header of the page.
- If you want to pass unlimited custom data that you want to track in a Post Payment event like IPN_Notified, PayPal_Returned, then, please check the feature chapter about Additional Data Items.
Setting Properties Programmatically using the Rich set of API.
Click Here to view the complete Class Diagram that you may use as a reference when you set properties from your code.
If you attach an event handler to this event, then the event handler method will be executed before the data is transferred to PayPal.
You can use Validation logic inside the Click Event handler of an 'Upload Complete Cart' button and based on a condition (user input) you can cancel the submission to PayPal. Please check the method CancelSubmission().
- The 'Upload Complete Cart' will POST BACK only IF the Click event is handled. If you do not handle Click event, your customer will be taken to PayPal website directly from the Client Side without any Server Round Trip.
Handling Instant Payment Notification (IPN) from PayPal:
This control can capture that notification and fire a server side event named IPN_Notified. This control not only just fires the event, but also collects all the transaction data from IPN and offers you a rich set of strongly typed relational object model as event argument object which is not only loved by all Object Oriented Programmers, but also revealing all the headaches from the developer about verification and other complex tasks in IPN Session.
Click Here to view the complete Class Diagram of ShoppingCartIPNEventArgs object.
By the way, the above example snippet does not show the detailed way of handling FRAUD attempts in order to simplify the overview of IPN_Notified event. So, you should check the pattern for payment verification, fraud detection and automated Product delivery.
If you do not want to handle IPN_Notified event from the same page, rather if you want to handle IPN_Notified event from a dedicated page, you can do that too. Simply do not handle IPN_Notified event and set the Custom Notification URL from the Design Time Smart Tag Wizard -> Step 3 as shown here:
- If you use a Custom IPN URL to capture the IPN from a dedicated page, you can still get the benefit of firing IPN_Notified event and capture all IPN data from event argument object from that dedicated page. How ? Please check the chapter for IPNHandler Component.
If you handle IPN_Notified event, then, setting Custom Notification URL will have NO EFFECT. The control will always generate notify URL automatically to use the same page where the 'Upload Complete Cart' button is hosted so that the same 'Upload Complete Cart' button can fire IPN_Notified event.
If you do not handle IPN_Notified event and if you do not set any Custom Notification URL then, this control will not capture IPN at all. If you have specified any default IPN URL in your PayPal profile, then, PayPal will use that URL to send IPN for any transaction happens in your PayPal account in that case.
You should handle IPN_Exception event if you want to capture any Exception thrown in your IPN_Notified event handler method. By handling IPN_Exception event, you not only catch any exception that was fired beyond your IPN_Notified handler layer, but also you get rid of using TRY - CATCH block in your IPN_Notified handler which will enhances the readability of your code.
You do not need to turn IPN option ON from your PayPal account at all. This control will take care of everything for you.
Whenever your customer is transferred back to your website from PayPal website after completing or canceling a payment (pursuant to submission of your 'Upload Complete Cart' button), you can execute post payment business logic on your website by handling an event named PayPal_Returned. This control not only just fires the event, but also collects all the transaction data from PayPal if you have turned 'Payment Data Transfer' option ON from your PayPal profile. The event argument object of PayPal_Returned event offers you a rich set of strongly typed relational object model same like the event argument object of IPN_Notified event. This event will take care of notification validation so you just do not need to worry about any dirty code work, rather use the clean data returned by this event argument object.
Once you handled PayPal_Returned event of your 'Upload Complete Cart' button, your buyer will be taken back to your website after the payment is completed or canceled. You can check from your Event handler if the payment was proceeded or canceled as shown below:
If you do not handle PayPal_Returned event, then, your buyer will not be returned to your website by PayPal. So, you should handle this event if you want to bring your buyer back to your site.
If you want to redirect your customer to a different page after returning from PayPal, you can do so by setting the Custom Completed Return URL and Custom Canceled Return URL from the Step 4 tab of the 'Upload Complete Cart' button Design Time Wizard as shown here:
Notice the check box in the above screen shot. If you check this box, then, the Canceled Return URL will be auto generated so that you can handle both of the Completed and Canceled Return event from the same page. It is HIGHLY RECOMMENDED that you check this option.
If you prefer to use Custom Return URL as mentioned above, you can still fire PayPal_Returned event and collect the information about completed/canceled from your dedicated return page. How ? please check the chapter for PayPalReturnHandler Component.
- If you handle PayPal_Returned event, then, setting Custom Complete Return URL and Custom Canceled Return URL will have NO EFFECT. So, if you want to redirect the buyer to a dedicated page after PayPal return, then, make sure that you do not handle PayPal_Returned event and then, set the Custom Complete Return URL / Custom Canceled Return URL.
If you want to receive all the transaction data in PayPal_Returned event as you could in IPN_Notified event from ShoppingCartReturnedEventArgs, then, you need to turn 'Payment Data Transfer (PDT)' option On from your PayPal account. Once you turn PDT ON for your PayPal account, you will receive an Authentication Token which is called 'PDT Authentication Token'.
Once you get the PDT Authentication Token, from the design time smart tag, click Button Wizard and select the last tab "Step 4 (Payment Return / PDT)". In that tab, at the bottom of the Form, you will find the box for PDT Authentication Token. Set the PDT Authentication Token in that box as shown here:
After PDT Authentication Token is set, you can collect transaction data from the PayPal_Returned event argument object ShoppingCartReturnedEventArgs.
Click Here to view the complete Class Diagram of ShoppingCartReturnedEventArgs object.
- You do not need to enable PDT if you just need to collect Transaction ID from PayPal_Returned event. e.TransactionID is available even though if you do not set PDT Authentication token.