How to Add PayPal Integration to your WebMatrix Project
Microsoft's Webmatrix is a free, downloadable platform for developing Asp.Net websites. The availability of many templates makes building an impressive looking site very easy. If you're building an eCommerce site, you'll need to be able to handle payments. PayPal is a great way to accomplish this. I searched the Internet to find out how to integrate PayPal into my Webmatrix project and found many articles and examples. Unfortunately, I couldn't get any of them to work. After much frustration, I finally found a YouTube video that shows how to implement eCommerce by downloading PayPal Webmatrix helper. The video has no commentary and it's difficult to read the screen, so I thought I'd write this article to help others who are looking for the same information. I've also added to the functionality shown in the video as it only provides PayPal code for the Featured Item, leaving out the rest of the items. If you prefer to watch the video instead of reading this text, you'll find it at the bottom of this article.
Set Up a PayPal Test Account
You'll need to set up a business (seller) test account and a user (buyer) test account so that you can test your web application. You don't want to do any testing with your real PayPal accounts. Setting up the accounts is easy, but when it comes to the business account, PayPal isn't very clear on which credentials are used in which part of the application. I will help you with this and save you hours of trial and error. Go to https://www.sandbox.paypal.com/ to create your test accounts. "Sandbox" is PayPal's testing environment and is completely separate from their production environment.
After setting up the two accounts, click "Test Accounts' on the left side menu. Make note of the email address of the test personal (buyer) account. If you auto-generated the accounts, you will probably want to click "Reset" and change the passwords to something you'll remember.
Click "API Credentials" on the left side
I suggest that you copy and paste the API credentials into a notepad document so that you can refer to them as needed. Note that the API password isn't the same as the Account password.
Note: Don't log out of your account. When you test your application, you'll need to be logged into your PayPal Sandbox account for it to work..
Adding PayPal to the Bakery Website
(This assumes that you've downloaded and installed Webmatrix, and you've downloaded and unZipped the PayPal Helper dll.)
The Bakery project is a great way to learn Webmatrix and PayPal integration.
- Start Webmatrix. Click "Site from Template"
- Click "Bakery". Wait for the Bakery website to be built.
- Click "Files" on the left menu.
- From the top ribbon, click "New / New File". Select "CSHTML". Name the page "_AppStart.cshtml" and click the OK button.
- Right-click the "bin" folder on the left side. Select "Add Existing File". Navigate to the unZipped the PayPal.dll file and click "Open".
Setting The PayPal Credentials in _AppStart.cshtml
Double-click on the newly created _AppStart.cshtml file.
Select and delete all of the code and replace it with the following. Please note that you must use the API account ID from the credentials, not the account email address. The Account ID, Password, and Signature are each enclosed in double-quotes and separated with commas.
"Your PayPal Test Business API account ID",
"Your API Password",
"Your API Signature",
Add the PayPal Button for the Featured Item
Double-click the Default.cshtml file to edit it. Buttons need to be created in two places - one is the Featured Item area, and the other is the For Each loop. Look for the following line of code in the Featured Item section (near the top). Note that now we are using the business account Email address, not the API Account ID.
<a class="order-button" href="@Href("~/order", featured.Id)" title="Order @featured.Name">Order Now</a>
Replace it with the following:
var fButton = PayPal.ButtonManager.AddToCartButton.Create(
"Your Test Business Email Address",
var featuredButtonCode = new HtmlString(fButton.WebSiteCode);
Add the PayPal Button for each Item
Next we have to create PayPal buttons for each item listed below the Featured Item section. Look for the line of code that says:
<a class="order-button" href="@Href("~/order", p.Id)" title="Order @p.Name">Order Now</a>
Replace it with the following:
var button = PayPal.ButtonManager.AddToCartButton.Create(
"Your Test Biz Email Address",
var buttonCode = new HtmlString(button.WebSiteCode);
Finishing the Test
Save your project. Click on the project name in the upper left to select it, then click "Run" on the top ribbon. When you click on an "Add to Cart" button, you will be taken to PayPal's test site (Sandbox), where you can complete your transaction. Use the test buyer account and password as your PayPal login. To verify that the transaction went through, check your PayPal Sandbox account and look at "Test Email". You should see your transaction. If there were no error messages, but you don't see the results, try again and make sure you're logged into Sandbox using the same browser that Webmatrix is using. (Most likely Internet Explorer).
Notes and Caveats
I learned (the hard way) that there is a bug in the PayPal Webmatrix Helper DLL that only shows up when you try to use the production PayPal site. The DLL works perfectly with PayPal's Sandbox test site, but a bug in the Microsoft code prevents it from working with the real site. The Microsoft DLL passes the word "Production", but DLL is expecting "Live". It appears that Microsoft has abandoned this as the original beta release from January of 2011 is still the only release available. The good news is that you can download the source code, make a small change (see below), and rebuild the DLL.
The "source code" link above will take you to www.Codeplex.com. Search the forums for "Webmatrix Paypal". You'll find the details there. Basically, you have to locate the file:
Edit the xml file. Copy the code section under "live", paste it, and change the element name to "production". You need to end up with one paragraph called "live" and one called "production" with identical code.
Recompile the code and the new Paypal.dll will work. I noticed that I had to recompile in "Debug" mode or the compilation would fail.
The button code shown above is an example of how to create a PayPal button on-the-fly. Including that code in the Default page is not best practice. Once you understand the principles, it's best to place the button creation code in an admin page, like a page for creating new product entries. Otherwise every time someone views a product, a new button will be created in your PayPal account, making it harder to manage.
The Bakery project assumes that you'll be using SQL Server Compact Edition which comes with Webmatrix. You may notice that database connections are opened but are never closed. This is OK in SQL Server Compact, but not best practice when using commercial databases, even SQL Server (full version). You can easily fix that by inclosing all of your database code in a "Using" block.
using(var db = Database.Open("SQLServerConnectionString"))
Put all of your code that references the database between the opening and closing brackets of the Using clause. Any variables defined within that block will be out of scope once you leave it. In some cases nearly all of your code will be within the Using block. Once the Using block is exited, the database connection will be closed automatically. Failure to do this could result in exhausting all available connections which will ultimately cause your website to fail.