Hack 95 Hack the API Wrapper

Create a master-detail report with information collected directly from PayPal .

Looking up order information for your buyers can be hard work, especially if you process many orders a day. Here's an order-searching form in Visual Studio .NET that allows you to search the PayPal history by date range (which you can expand later to include other parameters). The results are displayed in a master-detail report , which consists of a list of transactions in a DataGrid and a transaction detail form for any given transaction, all with information obtained directly from PayPal!

Add two new forms to your test application, and change the code a little bit for the RunTransactionSearch() method to return a DataTable instead of a string:

1. Add a new form to your test application, call it frmSearch , and make it your startup form.

2. Add two DateTimePicker controls, and name them dtStart and dtEnd , respectively, and give each descriptive labels (e.g., Search , Start ).

3. Add a DataGrid control and name it dg .

4. Add a button to the frmSearch and name it btnSearch .

5. Add a label and name it lblStatus . This label tells the user what's going on while he waits for the request to be returned from PayPal.

Figure 8-10 shows an example of the complete form.

Figure 8-10. The new transaction search form

8.11.1 The Code

Update the RunTransactionSearch() method to return a DataTable instead of a string:

 public DataTable RunTransactionSearch(DateTime StartDate,TransactionSearchParam param){   DataTable table=new DataTable("results");   TransactionSearchRequestType transSearch=new TransactionSearchRequestType( );   // Set up the TransactionSearch   TransactionSearchReq request=new TransactionSearchReq( );   transSearch.StartDate=StartDate;   request.TransactionSearchRequest = new TransactionSearchRequestType( );   transSearch.Version = "1.0";   transSearch.CurrencyCodeSpecified = false;   transSearch.EndDateSpecified = false;   transSearch.StatusSpecified = false;   //set the params   transSearch.StartDate=StartDate;   transSearch.EndDate = param.EndDate;      #region args list   int args=1;   if(param.TransactionID!=""){     transSearch.TransactionID = param.TransactionID;     args++;   }   if(param.Amount!=""){     transSearch.Amount = new BasicAmountType( );     transSearch.Amount.Value = param.Amount;     args++;   }   if(param.PayerEmail!=""){     transSearch.Payer = param.PayerEmail;     args++;   }   if(param.Currency!=""){     transSearch.CurrencyCodeSpecified = true;     args++;   }   if(param.ItemNumber!=""){     transSearch.AuctionItemNumber = param.ItemNumber;     args++;   }   if(param.LastName!=""){     transSearch.PayerName = new PersonNameType( );     transSearch.PayerName.LastName = param.LastName;     args++;   }   if(param.FirstName!=""){     transSearch.PayerName = new PersonNameType( );     transSearch.PayerName.FirstName = param.FirstName;     args++;   }   if(param.PaymentStatus!=""){     transSearch.StatusSpecified = true;     args++;   }   if(param.PaymentType!=""){     transSearch.TransactionClassSpecified = true;     args++;   }   #endregion   request.TransactionSearchRequest=transSearch;   //if there are more than 0 args set, run the transaction   if(args>0){     //run the transactioon     TransactionSearchResponseType response =                          service.TransactionSearch(request); 1.  if(response!=null){       if(response.PaymentTransactions!=null){         //build the columns out         DataColumn cTransactionID=new DataColumn("TransactionID");         DataColumn cFeeAmount=new DataColumn("FeeAmount");         DataColumn cGrossAmount=new DataColumn("GrossAmount");         DataColumn cNetAmount=new DataColumn("NetAmount");         DataColumn cPayer=new DataColumn("Payer");         DataColumn cPayerDisplayName=new DataColumn("PayerDisplayName");         DataColumn cStatus=new DataColumn("Status");         DataColumn cTimestamp=new DataColumn("Timestamp");         DataColumn cType=new DataColumn("Type");         table.Columns.Add(cTransactionID);         table.Columns.Add(cFeeAmount);         table.Columns.Add(cGrossAmount);         table.Columns.Add(cNetAmount);         table.Columns.Add(cPayer);         table.Columns.Add(cPayerDisplayName);         table.Columns.Add(cStatus);         table.Columns.Add(cTimestamp);         table.Columns.Add(cType);         DataRow dr;         foreach(PaymentTransactionSearchResultType trans in                                  response.PaymentTransactions){           dr=table.NewRow( );           dr["TransactionID"]=trans.TransactionID;                 dr["FeeAmount"]=GetAmountValue(trans.FeeAmount);                 dr["GrossAmount"]=GetAmountValue(trans.GrossAmount);                 dr["NetAmount"]=GetAmountValue(trans.NetAmount);                 dr["Payer"]=trans.Payer;                 dr["PayerDisplayName"]=trans.PayerDisplayName;                 dr["Status"]=trans.Status;                 dr["Timestamp"]=trans.Timestamp.ToLongDateString( );                 dr["Type"]=trans.Type.ToString( );                 table.Rows.Add(dr);         }         }            }           }else{     throw new Exception("You must specify at least one search parameter");   }      return table; } 

Line 1 begins the main change to the code and is responsible for building out the DataTable. Its execution is pretty straightforward and follows the same principal as appending the return values to a string: just loop through the results, adding a row for each array element.

8.11.2 Running the Hack

Add this code to the btnSearch Click event to call the API wrapper and set the DataGrid.DataSource property:

 private void btnSearch_Click(object sender, System.EventArgs e) {   string username = "MyAPIUserName";   string password = "MyAPIPAssword";   string certPath = "MyCertPath";   string url = "https://api.sandbox.paypal.com/2.0/";   DateTime dStart = dtStart.Value;   DateTime dEnd = dtEnd.Value;   //let the user know what's going on   lblStatus.Text = "Contacting Paypal";   PayPalAPI.APIWrapper api =                          new PayPalAPI.APIWrapper(username,password,certPath,url);   PayPalAPI.APIWrapper.TransactionSearchParam param =                          new PayPalAPI.TransactionSearchParam( );   param.EndDate = dEnd;   System.Data.DataTable table = api.RunTransactionSearch(dStart,param);   dg.DataSource = table;   lblStatus.Text = "Finished"; } 

This code, activated when the Search button is clicked, performs the search and displays the results in the DataGrid, as shown in Figure 8-11.

Figure 8-11. Nicely formatted search results

Finally, create a detail form that calls the GetTransactionDetails() method of the API wrapper, and output the results to a label control:

1. Add a form named frmDetail .

2. Add a label named lblTransactionID .

3. Add a label named lblResponse .

4. Add three public string fields named UserName , Password , and TransactionID .

5. Add an event handler for the form's load event and call it Form_Load .

Add an event handler for the double-click event of the DataGrid, and insert code to grab the selected transaction ID:

 private void dg_DoubleClick(object sender, EventArgs e) {      DataGridCell cell=dg.CurrentCell;   //the transaction ID is in the first column   string transactionID = dg[cell.RowNumber,0].ToString( );       frmDetail detail=new frmDetail( );      //set the form values   detail.TransactionID=transactionID;   detail.Show( ); } 

Finally, add code to the Load event of the detail form, which calls the API wrapper GetTransactionDetail( ) method:

 private void frmDetail_Load(object sender, System.EventArgs e) { string username = "MyAPIUserName"; string password = "MyAPIPassword"; string certPath = "c:\mycertificate.cer"; string url = "https://api.sandbox.paypal.com/2.0/";   //let the user know what's going on   lblResponse.Text="Contacting Paypal....";   PayPalAPI.APIWrapper api=new PayPalAPI.APIWrapper(UserName,Password,certPath,url);   lblResponse.Text=api.GetTransactionDetail(TransactionID,"\n");   lblTransactionID.Text=TransactionID; } 

When you perform a search, the results will look something like Figure 8-12.

Figure 8-12. Just the transaction you were looking for

With the master-detail report generated by this project, you'll be effectively duplicating the History tab from the PayPal web site, albeit in your own application, fully customized and supplemented with your own feature set. See the next section for an example of how this approach can be especially useful.

8.11.3 Importing into Quicken and QuickBooks

If you're a Quicken or QuickBooks user, you've probably discovered that PayPal's "Download My History" feature (found in the History tab) provides nothing more than rudimentary support for converting transaction data into a form that Quicken or QuickBooks can understand. Fortunately, the PayPal API provides the perfect opportunity to build your own customizedand, most importantly, automatedmeans of importing your PayPal transactions into your accounting software.

Regardless of the type of accounting software you're using, you need to start by assembling a table of transaction data from your PayPal history using the RunTransactionSearch method described earlier in this hack. The tricky part is to make sure you don't import the same transaction twice, and there are a few ways to accomplish this. The easiest way is probably to confine the table to a fixed date range using the StartDate and EndDate parameters. So, if you run your importer project once a week, restrict your search results to those transactions between 12:00:01 a.m. Monday morning and 12:00:00 midnight the following Sunday.

The next step is to get your data into Quicken or QuickBooks. The easiest approach is probably to have your application create an Open Financial Exchange (OFX) file and then manually import the file into Quicken or QuickBooks. For details on the OFX format, go to http://www.ofx.net.

Previously, you would have had to create a Quicken Interchange Format (QIF) file for Quicken or an Import Interchange Format (IIF) for QuickBooks. However, both of these formats appear to be deprecated in favor of the more universal OFX schema.

If you really want to make the connection between PayPal and QuickBooks as slick as possible, you'll want to dispense with the task of manually importing your data. Instead, you can connect your application to QuickBooks via Intuit's QBXML Request Processor API and send your transaction data to QuickBooks seamlessly (and automatically). For documentation and an SDK, visit http://developer.intuit.com/.

Rob Conery, Dave Nielsen, and David A. Karp