API Usage Overview

Using the PayPal API is a little different from most of the other APIs discussed in this book. The majority of the time, one of PayPal's servers will initiate the process by contacting your server. This is an "Instant Payment Notification," which is sent whenever money is transferred into your account by another user. Your server will then contact PayPal to confirm the transaction before any further actions are taken. Generally speaking, the only time in which your server will initiate new transactions with PayPal is to issue refunds. A few other functions are available, but are beyond the scope of this brief introduction. See Figure 10-1.

Figure 10-1

Developer Sandbox

The PayPal developer sandbox is quite impressive. Not only does it allow testing and exploration of the different account types as well as the API, but it also allows you to create any number of PayPal accounts with relative ease. When creating an account in the development system, fake billing information may be used, and the checking of account and credit card numbers is turned off.

Note 

Although most of the validation code is turned off or relaxed for accounts created within the developer system, the password rules have remained the same. Because you will be creating several accounts to test payments, refunds, and the like, you will need to manage all of those new accounts. While traditional methods like writing it all down on a sticky note work fine, I would heartily recommend Password Safe (http://passwordsafe.sourceforge.net/). Password Safe stores all of your usernames and passwords in a secure file, reducing the number of passwords you must memorize from some large number (I have 43) to one. Storing the program and database on a USB memory key allows for greater portability and an additional layer of security.

Within the development sandbox, you are going to need to create at least two separate accounts. First, you will need an account to represent you or your business. This will be the account to which most payments will be sent. Second, you will need a number of accounts that you will use to send money to the first account. I would recommend creating at least a few test accounts to send money with; try creating a few with two-line addresses, foreign countries, both short and long zip codes, and so on. Keep in mind that PayPal's restrictions on usernames may be far less restrictive than yours, and try to test multiple names in different character sets with your application before going live.

One particularly useful feature of the development sandbox is the ability to clear or fail any pending (or uncleared) payment on demand. This allows for immediate testing of pending payment and failed payment code. I would strongly recommend testing all IPN applications with all three major payment states (completed, pending, and failed). To manually affect a payment's status, select the details of the payment from within the PayPal Account Overview. On the Payment Details screen, there should be two links toward the bottom of the page, one for each option.

Note 

One problem you may encounter while using the sandbox is the inability to be logged into several different accounts at once. Once you have logged into the second account, all of your cookies get overwritten and all windows now belong to the most recently logged-in account. I've worked around that problem by using multiple web browsers concurrently, keeping one account open in Mozilla Firefox and another in Internet Explorer.