New PayPal Helper for WebMatrix

This week I’ve been at the PayPal Innovate Conference in San Francisco where Microsoft and PayPal have been talking to thousands of developers about the work we have been doing to create the easiest way to build apps that use PayPal for payments.  Today we are releasing the PayPal Helper for WebMatrix (in beta) which provides a simple way to do PayPal payments from the websites you build in WebMatrix.

What’s included in the PayPal Helper?

The helper we are shipping today, provides methods for the Button Manager API and Adaptive Payments API which are two of PayPal’s most popular APIs.  Here’s what PayPal says about both:

  • Button Manager APIs let you create, manage, edit, and delete Website Payments Standard buttons. Create payment buttons that let customers purchase single or multiple items, make donations, set up recurring payments, or buy gift certificates.
  • Adaptive Payments enable developers to build apps that process transactions. App builders can control the entire transaction within a single interface.
Downloading and installing the PayPal Helper
  1. Download and install WebMatrix
  2. Download the assemblies for the Helper (PayPal.dll, paypal_base.dll, log4net.dll)
  3. Create a new website or template in WebMatrix
  4. Create a bin folder off the root
  5. Copy and paste the assemblies into the bin
  6. You’re done!
PayPal Helper: Using Button Manager

Note – If you’re not familiar with the Button Manager API from PayPal, check out PayPal’s developer portal to find out more

The first thing you need to do is initialize the helper with your PayPal account credentials.  You can of course do this inline in the page, but the recommended option is to place the init call in your _AppStart.cshtml page so that it is called once when the app runs.  Here’s the init call code:

PayPal.Profile.InitializeBMProfile(
           “[API Username]”,
           “[API Password]”,
           “[API Secret]”,
           “sandbox”);

 

Next, to create a button on the PayPal side, call the method below.  When the Create AddToCart Button is fired, it returns the HTML code needed to display the button which we can then save to the database. We’ll typically use this HTML when we display the product detail page.

var payPalButton = PayPal.AddToCartButton.Create(
                                           Business : “[insert your sandbox account]”,
                                           ItemName : name,
                                           Amount : price.ToString(“N2”));

 

Now, if you login to PayPal (remember to use your Sandbox account if you have been using that) and click the “Profile” link and then “My Saved Buttons” under Selling Preferences, you will be able to see the button you have just created:

image

PayPal Helper: Using Adaptive Payments

Note – if you are not familiar with the Adaptive Payments service from PayPal, check out their developer portal for more information

I’m a big fan of the Adaptive Payment API because it has some cool features like Split Payments which allow you to pay other people “behind the scenes” without the customer knowing.  This is great if you have suppliers that you want to pay whenever an item gets sold through your online application but you don’t want to bother the customer with the details or let them know what you are paying your suppliers Smile

First up you’ll need to Initialize the profile, just like we did for Button Manager.  Here’s the code for that:

PayPal.Profile.InitializeFNProfile(               
       “ThreeToken”,
       “[API Username]”,
       “[API Password]”,
       “[API Key]”,
       “SOAP11”,
       “SOAP11”,
       “https://svcs.sandbox.paypal.com/”,
       “[App ID]”,
       “[PayPal User Email Address]”
   );

 

Next, we prepare the payment by setting up a single instance of a “receiver” which will the store that is receiving the payment.  After that we setup a list of receivers, which represents our suppliers (or other people that we need to pay after the transaction).  Up top I’ve done a quick calculation to give the supplier 10% of the product price, of course you would typically pull this information from a database where you stored the amount you want to pay them.

Once all that is setup we then call the PayPal.ChainedPay.Execute method passing in the receivers, an empty string (this is the sender of the payment – to be specified on PayPal’s side) as well as some information on the transaction. 

PayPal returns a response from which we can get a PayKey which represents the transaction on the PayPal side.  We then redirect the user to PayPal’s site, passing in the PayKey in the querystring so that PayPal knows how the transaction has been setup.

var supplierAmount = decimal.Round(product.Price * .10m, 2);
          
        var MyStore = new Receiver();
       MyStore.amount = product.Price;
       MyStore.email = “[Store Email]”;
        
        var Suppliers = new List<Receiver>();
       var Supplier = new Receiver();
       Supplier.email = “[Supplier Email]”;
       Supplier.amount = supplierAmount;
       Suppliers.Add(Supplier);

       PayPal.ChainedPay.Language = “en_US”;
       PayPal.ChainedPay.CancelUrl = “http://www.mystore.com/ohtoobad.cshtml”;
       PayPal.ChainedPay.ReturnUrl = “http://www.mystore.com/thanks.cshtml”;
       PayPal.ChainedPay.CurrencyCode = “USD”;
      �
       var response = PayPal.ChainedPay.Execute
           (MyStore, Suppliers, “”, “Test Payment”, “127.0.0.1”, “MyDevice”);
      �
       if (response == null) {
           Response.Write(“null”);
       }
       else
       {
           Response.Write(“full”);
       }   
      �
       var payKey = response.payKey;
       var redirectUrl = “https://www.sandbox.paypal.com/webscr?cmd=_ap-payment&paykey=” + payKey;           
      �
       Response.Redirect(redirectUrl);

 

This is what the consumer sees – note it’s just one line item to James’ test store.

image

Thanks to Chained Pay, the store sees this in it’s transaction log.  Note that our supplier has been paid automatically.

image

Open source

The code for the helper is based on the existing PayPal Base library for .NET that PayPal ship as part of the developer SDK.  This is already under the Apache license so it seemed natural to continue the tradition and release the helper in CodePlex under the Apache license.  You can download it here.

Future work

As this is a beta there’s a few items that we wanted to polish up for the final version.  

  • Remove dependency on Log4Net
  • Merge PayPal base assembly code with the new Helper assembly
  • Consolidate initialization methods for Button Manager and Adaptive Payments

As always please contact me if you have other suggestions, or leave feedback on the Codeplex project site.

Read More

New Facebook Helpers in WebMatrix Beta 2

Today we launched WebMatrix Beta 2 with a bunch of new features.  Here are my favorites:

  • Themes – quickly switch between different themes on your website
  • New HTML5 Templates in the box – rounded corners, transitions, sexy HTML5 templates. yum.
  • NuPack Package Management – get the bits you need, when you need em
  • New @Helper Syntax – adding helpers is now even easier

The new @Helper syntax makes it super easy to create your own helpers for WebMatrix.  Why would you want to do that? Well, there’s a couple of reasons.  Firstly, as a timesaver.  If you find yourself writing the same code or HTML time after time in your websites, it might be time to package up your code in a reusable Helper that you can utilize throughout your websites instead of writing the same thing over and over again and wasting time.  Secondly, if you are trying to foster a developer community that can use your service or website, then creating WebMatrix Helpers to make their life easier is a smart thing to do – because it removes friction for people to use your service.

Take the new Facebook Social Plugin Helpers in WebMatrix Beta 2 as an example.  They make use of the new @helper syntax to make it easier for developers to add social widgets to web pages.  The way you get these helpers is also worth mentioning, because it highlights a use of the NuPack technology that we announced today also.  Facebook’s Social Plugins Helper includes shortcuts to the following social widgets:

  • Login Button
  • Like Button
  • Comments
  • Recommendations
  • LikeBox
  • Facepile
  • LiveStream
  • ActivityFeed

As well as the ability to easily add metadata which shows up in rich ways across Facebook.

Getting your Helpers using NuPack

NuPack is an open source project driven by Microsoft that provides package management for developers in WebMatrix or Visual Studio 2010.  Within WebMatrix there is a package management page that you can visit where you can manage which packages are installed in your website projects.  With NuPack, it’s super easy to get Helpers and other things you’ll need to develop your website.

Note -  the current structure of our website if we create a new website from template.  Inside our app_data folder we have a bunch of folders including packages.  This is where the assets for our packages live.  We can see that we already have microsoft-web-helpers.1.0 installed by default and this package provides Helpers like Twitter, ReCapture and more.  There is also a packages.config file which contains information which points WebMatrix to the packages installed in App_Data.

image

To manage the packages installed in our website, we need to get to the admin page by simply navigating to http://localhost:xxx/_admin where xxx is your port number.  (Note – by default this is only enabled when running websites locally, as a security precaution).  If it’s the first time you’ve visited the page, you’ll be asked to create a password, remember this for future visits to the package manager page.

image

Next, you’ll be presented with a list of packages that you can install to use within your website.  Clicking on the Install button next to the Facebook.Helper 1.0 will install the files and pre-requisites for the helper to work correctly.  In the case of the Facebook Helper there are no dependencies however.

image

image

Once installed, the package “explodes” (in a useful, not violent way) in your website, installing various assets.  If we now look at the structure of the website in WebMatrix we see the Facebook Helper package has been installed successfully:

image

The most important asset is the Helper itself – FacebookSocialPlugin.cshtml and you can see that it was installed under the App_code folder in the root of website.  In this particular helper, we’ve also included some docs which explain how to get started as well as a full reference for all the methods in the helper.

To get to the docs just navigate to http://localhost:xxx/facebook/docs/starthere.htm

Note – There is already a Facebook Helper included in the Microsoft-web-helpers library which provides a shortcut to adding the Like Button to your website.  The FacebookSocialPlugin helpers has the like button as well as all the other Facebook Social Plugins and other good stuff like Open Graph etc.  In the next release we’ll merge the two Helper libraries so they are consolidated.

@helper syntax

Let’s explore the Facebook Social Plugin Helper a little more to understand how to use the @helper syntax.  The naming of the FacebookSocialPlugins.cshtml file is a good place to start.  This name will be taken as the class name at runtime, so the developer will use FacebookSocialPlugins.Foo() when using the helpers within the file.  Exploring the file, we see that all the methods use the @helper syntax, which mixes markup and code so that it’s possible to build up quite complex HTML and then inject parameters from the method or from calculated values in the helper code itself. 

Let’s take the helper method “GetInitializationScripts” as an example.  This method emits the JavaScript required by Facebook to allow their Social Plugins to work and must be added to every page that wants to use the plugins.  It’s not a trivial amount of script and before the Helper I would have to goto Facebook’s developer portal, hunt it down and copy and paste into every page.  Now with the Facebook Social Plugins Helper I can simply add the method to my _Layout.cshtml page, and by default it’s included on every page.  That’s a nice timesaver.

@helper GetInitializationScripts() {
   <div id="fb-root"></div>
   <script type="text/javascript">
       window.fbAsyncInit = function() {
           FB.init({appId: '@FacebookSocialPlugins.AppId', status: true, cookie: true, xfbml: true});
        };
       (function() {
           var e = document.createElement('script'); e.async = true;
           e.src = document.location.protocol +
           '//connect.facebook.net/en_US/all.js';
           document.getElementById('fb-root').appendChild(e);
       }());
   
       function loginRedirect(url) { window.location = url; }
   </script>
}

Notice how we inject he AppId from the FacebookSocialPlugins class?  This notion of mixing code and markup within a class method is very powerful and useful in lots of ways.  There’s a couple additional steps that you must do in order to have the Social Plugins working including calling the following method in _AppStart.cshtml.

@{
   FacebookSocialPlugins.Initialize("[Your App Id]", "[Your App Secret]", "bakery");
}

Secondly you must register the Facebook namespace in _Layout.cshtml which tells the page about the Facebook markup:

<html xmlns="http://www.w3.org/1999/xhtml" @FacebookSocialPlugins.FbmlNamespaces() >

 

Normally this would be a copy and paste from the depths of the Facebook developer portal, now it’s simply a case of using the Helper and you’re done.

This then clears the path for us to easily add Facebook’s Social Plugins to a WebMatrix website:

    <p>
   @FacebookSocialPlugins.Comments()
</p>

 

Results in:

image

It’s important to note that some Social Plugins require your site to be published to an external host that Facebook can communicate back and forth to.

I recommend checking out the documentation which comes as part of the Helper NuPack for more information on getting started, simply press the “run” button in WebMatrix  with startHere.html opened to browse the docs.

image

Other good reading on WebMatrix Beta 2

Read More