Hack 91 Refund Payments with the API

Use the API wrapper class to call the RefundTransaction API and refund a payment without logging into the PayPal web site .

Of several things you can do with the API (discussed in the introduction to this chapter), one of the most useful for PayPal's larger businesses is RefundTransaction , especially for customer service reps who have to process refunds routinely. Requiring your customer service reps to log into PayPal to process a refund requires a lot of time and unnecessary access to your account. With PayPal's new Refund API, however, you can create an application that retrieves payment transaction data and processes refunds directly from your own custom application. And just like GetTransactionDetails [Hack #90] , you can use the API wrapper to handle the basics and just add the refund-specific code.

The refund function call involves the use of three objects:

• RefundTransactionRequestType

• RefundTransactionReq

• RefundTransactionResponseType

The two Type objects are holders for information, while the Request object is used by the API service to send the information to PayPal. Here's an example of the code you need to add to your API wrapper:

 public string RefundTransaction(string TransactionID){   //the variable that will hold the return string   string sReturn="";   // Create the Refund Request   RefundTransactionRequestType refundRequest = new RefundTransactionRequestType( );      //set the memo so you know why you are refunding   refundRequest.Memo = "test via API"; 1.  //refund a full or partial amount   refundRequest.RefundType = RefundPurposeTypeCodeType.Full;   refundRequest.TransactionID = TransactionID;   refundRequest.Version = "1.0";   RefundTransactionReq request = new RefundTransactionReq( );   request.RefundTransactionRequest = refundRequest; try{   RefundTransactionResponseType response = service.RefundTransaction(request);    2.  string ErrorCheck=CheckErrors(response);                 //See Hack 92 for Transaction Error Handling   if (ErrorCheck!="") {     sReturn=("The transaction was not successful: " + ErrorCheck);   }   else {     sReturn=("Response: " + response.Ack.ToString( )+"\n Correlation ID                 "+response.CorrelationID+"\nTimestamp: "+response.Timestamp.ToString( ));   } }catch(Exception x){   sReturn="SSL Failure, the transaction did not go through. Error: "+   x.Message; }return sReturn; } 

You have a choice of how much money you would like to refund your customer. The preceding code refunds the full amount, but if you want to issue only a partial refund, specify the amount using PayPal's BasicAmountType by replacing line 1 with this code:

 refundRequest.RefundType = RefundPurposeTypeCodeType.Partial; BasicAmountType amount=new BasicAmountType( ); amount.Value=10.00; refundRequest.amount=amount; 

8.7.1 Running the Hack

To use the API wrapper [Hack #89] to process a refund, you must first create a transaction by using your Personal Sandbox account to send money to your Business Sandbox account. First, retrieve the transaction number from your Business Sandbox account [Hack #88] .

Next, add the RefundTransaction code to your API wrapper class in the same way that GetTransactionDetail is added to the API wrapper class in [Hack #90] . Then, create a button called cmdRefund on your form and add the following code to its OnClick event:

 private void cmdRefund_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/";         lblResponse.Text="Contacting PayPal...";         PayPalAPI.APIWrapper api = new                 PayPalAPI.APIWrapper(username,password,certPath,url);         lblResponse.Text = api.RefundTransaction(transactionID); } 

The form should look something like the one in [Hack #90] .

Finally, to run the hack, run your PayPalTestApp application, enter the transaction number into the transaction ID field and press the GetDetails button. When you've successfully retrieved the details, press the Refund button to complete the refund.

Confirm that your transaction has been refunded by logging into your Sandbox Personal account.

8.7.2 The Results

The only response you really need from PayPal once you've executed the refund is one that tells you whether it was successful. The Ack property (which indicates acknowledgement , not a shriek of pain) contains the status of the refund and is set to Success if all went well. If the refund did not go through, you likely violated a PayPal rule, such as issuing a partial refund greater than the purchase price or trying to refund a payment more than 30 days after the payment.

The CheckErrors() function on line 2 handles this task (see [Hack #92] for details). For rules governing PayPal refunds, open your Sandbox Business account and search the online help for refunds . See [Hack #9] for more information on using PayPal's help system.

-- Rob Conery, Michael Blanton, and Dave Nielsen