Other Web APIsSo far in this book, you have explored several leading APIs in detail. This chapter provides a verybrief introduction to some additional Web APIs. You will also learn how to locate additional APIsfor use in your programs. This chapter specifically covers the following: .An introduction to InterFax faxing Web API .An example of sending a fax programmatically from Visual Studio .NET .An introduction to the UPS API .An example of submitting a request to the UPS API .An introduction to the FedEx API .An example of submitting a transaction using FedEx Ship Manager Direct .An introduction to the Bloglines API .Information on how to locate additional Web service APIsIf you want more information about any of the Web APIs covered in this chapter, visit the respec- tive Web sites. Comprehensive documentation and code examples are available for each of them. Faxing APIsIf you are like me, I m sure that at times you have wanted to send a fax from your computer with- out using a phone line. Luckily for us, fax Web APIs are available today that enable us to sendfaxes from our own programs with just an Internet connection. For example, a company calledInterFax Inc. (www.interfax.net) offers an XMLWeb service that allows faxes to be sent withand without file attachments to one or more fax numbers worldwide.
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Cheap Web Hosting services
InterFax charges per page to use the service, and you purchase a prepaid number of pages beforeusingthe service. More information about pricing is available online at http://www.interfax.net/ scripts/prices.asp?lang=en. For example, at the time of this book s writing, faxes can be sent usingthe service for a charge of approximately 7 cents to 11 cents per page depending on volume. InterFax offers a free developer program that allows you to send unlimited faxes to a single fax number, such as to your own fax number, for testing your programs. I ll quickly walk you through the steps forobtaining a developer registration and sending a test fax using the service. Setting Up a Free Developer AccountTo set up a free developer account, go to http://www.interfax.net/en/dev/index.html, as shownin Figure 7-1. Figure 7-1Click the Sign Up Now link and fill in the information requested on the registration form shown inFigure 7-2. 164Chapter
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Cheap Web Hosting services
Because PayPal has provided a test client called API Client that illustrates how to use each of the avail- able methods, they are not covered in this chapter. Please visit the Help Center in the PayPal DeveloperZone for more information on downloading the API Client project. Other Ways to Use the PayPal APIIn the previous section, you looked at an example of how to use the PayPal API in your applications. Here are a couple of other ideas of how you might use the PayPal API: .Perform a search for transactions that were denied so you can follow-up with those customersto make alternate payment arrangements. .Perform a search for transactions that were processed over a particular time period to calculateyour total sales revenue. Third-Party PayPal ExtensionsVarious third parties offer solutions that work with PayPal, including some that use the API. You canfind a list of what some of these third parties have done on the PayPal Web site. The list is currentlylocated at: https://www.paypal.com/us/cgi-bin/webscr?cmd=p/pdn/3p-solutionsSummaryPayPal is a leading online payment provider that allows buyers and sellers to exchange funds in variousways. Buyers can securely provide credit card and other payment methods to PayPal and then PayPalhandles disbursement to the specified merchant. PayPal has made various features available in an API tomerchants so that the transactions can be managed from custom programs. You learned the various fea- tures supported by the PayPal API, as well as how to call the API using SOAP. Additional examples areprovided in the API Client project in the Help Center of the PayPal developer site, as well as in the otherdocumentation contained on that site. With PayPal under your belts, let s turn to Chapter 7 where you learn about several additional APIs, including InterFax, UPS, FedEx, and Bloglines. 162Chapter
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Adult Web Hosting services
request.RefundTransactionRequest.Version = 1.0 request.RefundTransactionRequest.TransactionID = ID of your transaction Dim response As New PayPal.RefundTransactionResponseTyperesponse = pp.RefundTransaction(request) Exit Subhandle_error: MsgBox(Err.Description) Exit SubEnd Sub9.Input your specific User Name, Password, .CER Certificate location/name, and Transaction the lines of code where indicated. 10.Select File.Save All to save all changes to the project. 11.Select Debug.Start (or press F5) to run the project. Click the button to run the example. 12.After the operation finishes successfully, log in to the test personal account that you used earlierto perform the transaction. That is the account that should receive the refund. 13.Upon logging in to that account, you should see a window similar to Figure 6-13 that displays entry from the test business account. Figure 6-13These materials have been reproduced with the permission of PayPal, Inc.Copyright 2003 PayPal, Inc. All rights reserved.
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Adult Web Hosting services
.Payer E-mail address of buyer. .Receiver E-mail address of receiver. .ReceiptId PayPal Account Optional Receipt ID. If specified, other search values ignored. .TransactionId Transaction ID of the buyer or seller. If specified, other search values ignored. .InvoiceId Invoice identification key as set by merchant for original transaction. .PayerName Various name combinations. .AuctionItemNumber Auction Item Number. If specified, other search values ignored. .TransactionClass Classification (examples include All , Payments , Sent , Received , and so on). .Amount Transaction amount that was charged to the buyer. .CurrencyCode Currency code to search for (examples include USD , GBP , EUR , andsoon). .Status Status of transaction (examples include None , Completed , Failed , Pending , Denied , and so on). The TransactionSearchmethod responds by returning a TransactionSearchResponseobject about the transactions meeting the specified criteria. GetTransactionDetailsThe GetTransactionDetailsmethod requests details about a payment. Currently, theGetTransactionDetailsRequestobject that is passed to the GetTransactionDetailsobject sup- ports the following properties: .TransactionId Required. Unique identifier for a transaction. .Version Required. String that represents the version of the response schema (currently The GetTransactionDetailsmethod responds by returning a GetTransactionDetailsResponseobject with details about the particular transaction. MassPayThe MassPaymethod allows a merchant to make payment distribution requests. The MassPayRequestobject that is passed to the MassPaymethod currently supports the following properties: .EmailSubject E-mail subject to use in e-mail to recipients. .ReceiverEmail Required. E-mail address of recipients. .Amount Required. Amount to send to each recipient. .UniqueId Unique ID for each recipient to be used for tracking purposes. .Note Customized note for each recipient. The MassPaymethod responds by returning a MassPayResponseobject with details about the successor failure of the request.
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Cheap Web Hosting services
Executing a QueryNow that you have a basic idea of the types of operations supported by the PayPal API, let s look atsome simple code examples to see how they work. PayPal API calls can be executed using SOAPopera- tions. As you recall, with SOAPoperations, you have to specify the location of the WSDLfile thatdescribes the Web API and then create a proxy so that your program knows how to communicatewiththe Web API. Visual Studio .NET handles the creation of the proxy for you when you add a Webreference. Walkthrough Example Calling the PayPal API Using SOAP from Visual Studio .NETLet s walk through a step-by-step example of using SOAPto call the PayPal Web service from VisualStudio .NET. In this example, you call the RefundTransactionoperation to fully refund a prior trans- action that you manually created earlier in this chapter. 1.Open Visual Studio .NET and select File.New.Project. 2.Select Visual Basic Project as the Project Type, and select Windows Application as the Template. For the project name, specify PayPalSample, and for the path, specify the location where youwant the project to be created. Click OK to create the new project. 3.Drag and drop one command button from the Toolbox onto the form. 4.Add a reference to the PayPal API by selecting Project.Add Web Reference. For the URLfield, specify the location of the WSDLfile, such as: www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl5.Click the GO button so that Visual Studio can locate the PayPal Web API. 6.Change the Web Reference Name to PayPalso that you can use a shorter name in your project. 7.Click the Add Reference button to add the reference to your project. Visual Studio .NET uses theWSDLfile to identify the methods that are available for execution from your project. 8.Add the following procedure to Form1to the Clickevent of the second button: Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As _ System.EventArgs) Handles Button1.ClickOn Error GoTo handle_error create a reference to the paypal serviceDim pp As New PayPal.PayPalAPIInterfaceService set the required credentials for using the servicepp.RequesterCredentials = New PayPal.CustomSecurityHeaderTypepp.RequesterCredentials.Credentials = New PayPal.UserIdPasswordTypepp.RequesterCredentials.Credentials.Username = Your PayPal DevZone userid pp.RequesterCredentials.Credentials.Password = Your PayPal DevZone pwd pp.RequesterCredentials.Credentials.AuthCert = my_paypal_certificate.cer pp.Url = https://api.sandbox.paypal.com/2.0/ Dim request As New PayPal.RefundTransactionReqrequest.RefundTransactionRequest = New PayPal.RefundTransactionRequestType160Chapter
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Cheap Web Hosting services
At this point, you must convert the .p12 certificate into the type of certificate required by your program- ming language. For example, to use the PayPal API from Visual Studio .NET, you convert the .p12 certifi- cate to a .CER certificate. To do so, you first should double-click the previously created my_paypal_cert.p12file. The Certificate Import Wizard appears. Follow the prompts to import the certificate, specifying yourcertificate password when prompted. Accept the defaults, and a message should appear indicating that theimport was successful. Next, after the wizard completes, you export the .p12 certificate from Internet Explorer to a .CER file. Todo so, open Internet Explorer, and then select Tools.Internet Options and select the Content tab. Clickthe Certificates button and select the .p12 certificate that you use to access the Sandbox. It should appearon the Personal tab. Click the Export button, and a Certificate Export Wizard appears. Follow the wizardto accept the defaults, and on the File to Export screen, select Browse and specify the path and filenamefor the new certificate. Click Save to save the file and follow the prompts to finish the wizard. It isimportant that you keep track of the name and location where you saved the .CER file because you willneed it in calls to the API later on. Anatomy of a PayPal API QueryNow that you have all the messy setup out of the way, let s take a look at how a PayPal API query isstructured. You then see a simple example of how to execute queries using the API. Query SyntaxCurrently, you can call one of four methods of the PayPal API: RefundTransaction, TransactionSearch, GetTransactionDetails, and MassPay. Each of these is covered detail. RefundTransactionThe RefundTransactionmethod is used to request a payment refund. ARefundTransactionRequestis an object that is passed to the RefundTransactionmethod and supports the following properties: .TransactionId Required. Unique identifier for a transaction. .RefundType Type of refund. Currently Fullor Partial. .Amount Amount of refund. Required if partial refund. .Memo Custom comment about the refund. The RefundTransactionmethod responds by returning a RefundTransactionResponseobject. TransactionSearchThe TransactionSearchmethod requests a historical transaction search. Up to 100 exact matches canbe retrieved. Various criteria can be specified to limit the search results. The following properties aresupported by the TransactionSearchRequestobject that is passed to the TransactionSearchmethod: .StartDate Required. Starting date range to use for search. .End Date Ending date range to use for search. 158Chapter
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Cheap Web Hosting services
Open the text file in a text editor such as Notepad and separate the private key and the certificate intotwo separate files. The private key is indicated with the Begin and End RSAPrivate Key comment, certificate portion is indicated with the Begin and End Certificate comment. Save the private key called privatekey.pemand save the certificate in a file called certificate.pem. Other names be used. It is important that each file contains the comment in the correct syntax, with five dashes surroundingeach comment. Otherwise, you will receive an error later when trying to create the P12 certificate. Forexample, the privatekey.pem file should contain the following: —–BEGIN RSAPRIVATE KEY—–Your key is here—–END RSAPRIVATE KEY—– At this point, you have to use a cryptographic tool to convert the certificates to a PKCS12 (.p12) certifi- cate file. One example of such a tool is described in the PayPal documentation is OpenSSL, which isoffered in an easy installation version for Windows at www.slproweb.com. More information aboutOpenSSLcan also be found at www.openssl.org. Follow the instructions to download and installOpenSSL. Open a command window and navigate to the path where OpenSSL.exe is located (based on where the program). Copy your two .pem files to that same path to make this process easier. Typeopenssl.exe to run the program, and at the OpenSSLprompt, type the following command to convert files created previously: pkcs12 export inkey privatekey.pem in certificate.pem out my_paypal_cert.p12You are prompted to enter a password associated with the certificate. Make sure to write down this password for future use. Upon successful creation of the p12 certificate, a screen like the one shown 6-12 is displayed. Figure 6-12Type Exitto exit the OpenSSLtool. Verify that your .p12 certificate, called my_paypal_cert.p12, was created in that same directory. You need this file later, so copy it to a location where you can find it.
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Cheap Web Hosting services
Click the Details link, and a screen similar to Figure 6-11 is displayed. Figure 6-11These materials have been reproduced with the permission of PayPal, Inc.Copyright 2003 PayPal, Inc. All rightsreserved. Write down or electronically copy the Transaction ID value so you can use that transaction for testing theAPI in the code example later in this chapter. Obtaining and Converting a Security CertificateYou are now ready to perform the last setup step to enable you to use the API obtaining and convert- ing the security certificate. As mentioned previously, because the PayPal API deals with monetary trans- actions, you must use a higher level of security than you do with many other Web APIs discussed in thisbook. To obtain a certificate, log into PayPal Sandbox with your test business (seller) account. Click on the Profiletab, and then click the API Access link. Then, click the API Certificate Request link. Fill in the informationrequested to set up a certificate, and then click the Generate Certificate button. Click the Download buttonto download the text file that contains the certificate. Save the text file to a location on your hard drivewhere you can find it later. As another option, an e-mail is also sent that contains a link for downloading your certificate. Again, forthe test Sandbox environment, the e-mail is placed in your online inbox as opposed to being sent to youractual e-mail address. 156Chapter
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Adult Web Hosting services
Setting Up Test TransactionsNow that you have created a test personal account and a test business account, the next step is to fundthe accounts and create some test transactions. The API cannot be used to add funds to an account a transaction, but simply to work with existing transactions. Thus, you need to use the onlinetools to add some money to the test personal account and then send some money from that account test business account. To do so, log into developer.paypal.com (PayPal Developer Central), click tab, click the Launch Sandbox button, and log in with your test personal account. Begin by manually adding some money to the test personal account you want to use for the purchase. While logged in to the Sandbox account for that user, select Add Funds. Under options, select TransferFunds. Select the account and the dollar amount and click Continue. Because this is a test account, you also have to manually clear the transaction. From the Overviews the transaction should be listed as pending. If you click the Details link, an option to clear the transactionappears. Select the Clear Transaction link and the status of the transaction changes to Completed. Next, you need to set up one or more test transactions so you can work with those transactions using While still logged in to the test personal account, click the Send Money tab. Fill in the informationfor the test business account, including the e-mail address you assigned to that account and the amountyou want to pay it. Follow the online instructions to complete the transaction. Verify that the transaction was successful by logging out of the test personal account and by logging test business account. The payment should be shown on the Overview page, as shown in the exam- ple in Figure 6-10. Notice that the available balance has been reduced by the PayPal service fee. Figure 6-10These materials have been reproduced with the permission of PayPal, Inc.Copyright 2003 PayPal, Inc. All rights reserved.
Note: If you are looking for good and high quality web space to host and run your application check Lunarwebhost Adult Web Hosting services