Hack 94 Search for PayPal Transactions

Use the TransactionSearch API call to find a transaction based on several different criteria .

The ability to search for transactions is another powerful PayPal API function. You can find transactions by using several different criteria:

Start and end dates

The bounding time frame of the search, down to the second.

Amount

The payment amount (e.g., 54.00 ).

Currency type

The three-letter currency code (e.g., USD ).

Item number

The item number of a sale item. This item number is the same as the product code you might have specified for your product when it was sold (a SKU, for example).

Payer email, last name, first name , salutation

The name and email address of the person or entity who sent the payment.

Receipt ID

PayPal issues a receipt ID for each transaction, much like the transaction ID. If a customer has a question or an issue about her order, she might offer this number to you.

Payment status

This can be pending , completed , failed , denied , refunded , or canceled_reversal . For instance, specify completed here to show only completed transactions.

Payment type

This can be payment , bill , refund , and so on (see the PayPal API Developer's Guide , available at PayPal Developer Central, for the full list). Using the payment type as a search parameter, you can show only those payments that were refunds , or perhaps those received by billing.

The search is an inclusive search: the more parameters you specify, the more limited your result set will be. At the time of this writing, partial values, Boolean, wild card, and regular expression terms are not supported, although PayPal might add support for these types of searches in the future. Figure 8-9 shows an example of the output.

Figure 8-9. The results of the TransactionSearch API call

8.10.1 The Code

The following code sets up a separate class for holding search parameters to be passed. The results of the search are put into an array object, through which you can loop to view the return information:

 1.  public class TransactionSearchParam { public DateTime EndDate=DateTime.Now; public string TransactionID=""; public string Amount=""; public string Currency=""; public string ItemNumber=""; public string PayerEmail=""; public string LastName=""; public string FirstName=""; public string Receiver=""; public string ReceiptID=""; public string PaymentStatus=""; public string PaymentType=""; } //the search wrapper method; the StartDate is required so pass //it in as an argument public DataTable RunTransactionSearch(DateTime StartDate,                 TransactionSearchParam param, string delimiter){ //setup the return string object string sReturn="";   //create the Type object, which will hold the search parameters TransactionSearchRequestType transSearch=new TransactionSearchRequestType( ); // Set up the TransactionSearch TransactionSearchReq request=new TransactionSearchReq( ); transSearch.StartDate=StartDate; //set the params transSearch.StartDate=StartDate; transSearch.EndDate = param.EndDate; //count the number of arguments to be passed in //you may want to have some mininum logic involved int args=0; if(param.TransactionID!=""){ transSearch.TransactionID = param.TransactionID; args++; } 2.  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++; 3.  } //set the request type object with the one //filled out with params request.TransactionSearchRequest=transSearch; //run the transactioon TransactionSearchResponseType response = service.TransactionSearch(request); //make sure the response was created if(response!=null){ StringBuilder sb=new StringBuilder( ); sb.Append("Status: "+response.Ack.ToString( )+delimiter); sb.Append("*********** Results ***************"+delimiter); 4.  sb.Append( "Ack"+response.Ack +delimiter); 5 .  if(response.PaymentTransactions!=null){ // Loop through and return the values   foreach(PaymentTransactionSearchResultType trans in                  response.PaymentTransactions){     sb.Append("TransactionID: "+ trans.TransactionID+delimiter);     sb.Append("FeeAmount: "+ GetAmountValue(trans. FeeAmount)+ delimiter);       sb.Append("GrossAmount: "+ GetAmountValue(trans.GrossAmount)                 + delimiter);     sb.Append("NetAmount: "+ GetAmountValue(trans.NetAmount)+ delimiter);     sb.Append("Payer: "+ trans.Payer+delimiter);     sb.Append("PayerDisplayName: "+ trans.PayerDisplayName+delimiter);     sb.Append("Status: "+ trans.Status+delimiter);     sb.Append("Timestamp: "+ trans.Timestamp.ToLongDateString( )+ delimiter);     sb.Append("Type: "+ trans.Type.ToString( )+delimiter);     sb.Append("--"+delimiter+delimiter);   }   } sReturn=sb.ToString( ); }else{   sOut=sb.ToString( )+delimiter+"No Results!"; } 

Passing search parameters with a dedicated class, TransactionSearchParam (on line 1) eliminates the extra coding involved when passing parameters as arguments. If the parameters ever change, there is little work to do to bring your code up to date. But the best part is that your method signature doesn't change and break all your code. The section of if statements from line 2 to line 3 fills out the TransactionSearchRequestType object that the PayPal API needs to run the search. If your search returns any values, Ack is set to Success on line 4. Then, provided that the result set is not empty (line 5), the code starts looping through the collections to retrieve the information. This example is pretty straightforward, and it holds all the transaction information for each returned transaction.

8.10.2 Running the Hack

Add the RunTransactionSearch code to your API wrapper class [Hack #93] .

Next, add three text boxes ( txtStartDate , txtEndDate , and txtEmail ) and a button ( cmdSearch ) to From1 . Then, add the following code to the button's Click event:

 private void cmdSearch_Click(object sender, System.EventArgs e) {         string username=txtUserName.Text;         string password=txtPassword.Text;         string transactionID=txtTransactionID.Text;         string certPath="C:\certificate.cer";         string url = "https://api.sandbox.paypal.com/2.0/";         PayPalAPI.APIWrapper api=new DateTime StartDate = DateTime.Parse (txtStartDate.Text); DateTime EndDate = DateTime.Parse(txtEndDate.Text); string Email = txtEmail.Text lblResponse.Text = "Contacting Paypal..."; PayPalAPI.APIWrapper api = new PayPalAPI.APIWrapper(username, password,                 certPath, url); PayPalAPI.API.APIWrapper.TransactionSearchParam param =                  new PayPalAPI.APIWrapper.TransactionSearchParam( ); param.EndDate = EndDate; param.PayerEmail=Email; lblResponse.Text = api.RunTransactionSearch(StartDate, param, "\n"); } 

Run the form, fill out the text boxes with your date range and email address, and click the Search button. The information supplied on the form will be passed to the wrapper class, which will prepare the request and then call the RunTransactionSearch API. When successful, the list of transactions will appear in the label control.

Rob Conery and Dave Nielsen