PayPal introduces PayPal X Platform Toolkit for Google App Engine

Hello App Engine Developers!
My name is Praveen Alavilli (@ppalavilli) and I work as a developer evangelist for PayPal's X Platform at PayPal.com. I want to take the opportunity to introduce you to our new open source toolkit for Google App Engine that provides an easy way to integrate your Java apps running on App Engine with the new PayPal's Adaptive Payments API. Currently this is a Java toolkit explicitly for App Engine Java, but a Python version will be coming out soon.

Background
The Adaptive Payments API provides a set of core services offered by the PayPal X Open Global Payments Platform to enable developers to embed payments into their applications, services, and platforms. The Adaptive Payments APIs offer several new payments functionality like Split Payments and Preapprovals, that enable developers to implement a variety of monetization models - freemium, subscriptions, pay-per-use, value-added-services, micro-transactions, e-commerce, etc. in their applications built and running on the App Engine. Whether you are building an application for Businesses to process back-end disbursements or payouts to affiliates, or building a social or gaming app for Facebook / Twitter / Open Social, or building a Desktop gadget for premium content, or building a Geolocation app that only helps users find places and people around where they are but even help in transacting them, or building a Web2.0 AJAX app that mashes up content and services, or several more use cases enabled by App Engine, now you can use the PayPal X toolkit to enable payments in them as it fits the needs.

Using the toolkit
Getting started with App Engine toolkit is easy. You can either checkout the source code from svn and import it into your Eclipse project or simply download the prebuilt jar file and include it in your application's class path (/WEB-INF/lib). Similar to other APIs that you might have used, you would need PayPal API Credentials to authenticate your API requests. With the toolkit you simply create an "APICredential" object from one of your application initialization methods (in most cases from your Servlet init() method) and load the API Credentials that you have obtained from the PayPal Sandbox. (Please refer to PayPal's Sandbox guide for more detailed information on how to obtain them).

// Obtain the credentials from your configs 
credentialObj = new APICredential();
credentialObj.setAPIUsername(getServletConfig()
    .getInitParameter("PPAPIUsername"));
credentialObj.setAPIPassword(getServletConfig()
    .getInitParameter("PPAPIPassword"));
credentialObj.setSignature(getServletConfig()
    .getInitParameter("PPAPISignature"));

// setup your AppID from X.com
credentialObj.setAppId(getServletConfig()
    .getInitParameter("PPAppID"));

// setup your Test Business account email 
// in most cases this would be associated with API Credentials
credentialObj.setAccountEmail(getServletConfig()
    .getInitParameter("PPAccountEmail"));

// add required error condition checks
//....

Once the APICredentialObj is initialized successfully, save it in the application's local context so you do not need to reinitialize it on every request.
At its core, the Adaptive Payments API provides 5 generic API methods: Pay, Pay Details, Preapproval, Preapproval Details, Cancel Preapproval, Refunds, and Convert Currency. The toolkit provides the base API Request classes required to make those API calls. To make it even simpler, the toolkit also provides a few functional API wrapper classes that not only abstracts the APIs in terms of the functionality exposed (SimplePay, ChainedPay, ParallelPay, CreateSimplePreapproval, CreatePreapprovalForPeriodicPayments, PreapprovedChainedPay, etc.) but also provides a few exceptions that helps in handling errors more easily than the generic API Responses.

A Simple example
To give you an example, let's say you are building a SaaS model application on App Engine that you charge your customers based on their usage. While on-boarding customers to use your app, you can use the Preapproval API to obtain authorization from your customers to charge them for the app/service based on their usage in the future. In this case you can simply use the 'CreateSimplePreapproval' to create and send a request as below:

try {

  // CreateSimplePreapproval request to setup a simple 
  // preapproval with no Payment Period Set
  CreateSimplePreapproval simplePreapproval = 
      new CreateSimplePreapproval();

  // set the API Credentials object (as given in the code above)
  simplePreapproval.setCredentialObj(credentialObj);

  // starting date in yyyy-MM-dd format
  simplePreapproval.setStartingDate("2010-06-25");

  // ending date in yyyy-MM-dd format 
  // in this case it's for an year from the starting date
  simplePreapproval.setEndingDate("2011-06-25");

  // set max total amount of all Payments
  simplePreapproval.setMaxTotalAmountOfAllPayments(52.00);

  // set max amount for each payment - let's say $1
  simplePreapproval.setMaxAmountPerPayment(1.00);

  // set max number of payments allowed - (52 weeks)
  simplePreapproval.setMaxNumberOfPayments(52);

  // set where to send the user in case of a cancellation
  simplePreapproval.setCancelUrl(req.getRequestURL() +
      "?action=preapproval&cancel=1");

  // set where to return the user after successful approval
  simplePreapproval.setReturnUrl(req.getRequestURL() + "?
    return=1&action=preapproval&preapprovalKey=${preapprovalKey}");

  /* Set other required fields */
  // ... //

  // set memo for user's transaction history
  simplePreapproval.setMemo("Preapproval for GAE Sample");

  // send the request
  PreapprovalResponse preapprovalResponse = 
      simplePreapproval.makeRequest();

  } catch (//...exceptions go here...//) {
  // handle exceptions as necessary

}

In this case, when the 'AuthorizationRequiredException' is thrown, your application would need to redirect the user to PayPal for authorizing the preapproval. The 'getAuthorizationUrl' method takes care of building the PayPal authorization url along with the Preapproval Key returned by the Preapproval API. Once the user authenticates and authorizes the preapproval request on PayPal.com, the user will be redirected back to your 'returnUrl' along with the preapprovalKey, which your application can verify by using the 'PreapprovalDetailsRequest' and store it in it's own app engine data store securely. From that point onwards, whenever the user needs to be charged for their usage of the application, the application can use one of the 'PreapprovedSimplePay' or 'PreapprovedParallelPay' or 'PreapprovedChainedPay' classes to make a payment on behalf of the user. Please refer to the sample apps to understand how to use the other classes provided by the toolkit to make Parallel,Chained or Simple Payments. For eg. the PicMartServlet.java in the PicMart sample app shows how you can make a parallel payment to two receivers at the same time.

Further examples
As mentioned earlier, if you are building a social game where users can buy digital goods (eg. micro-payments) and virtual currencies while playing a game, you can use the same Preapproval API to obtain authorization from them so you could charge their PayPal accounts as and when needed, without requiring them to re-enter their payment information or redirect to PayPal for authorizing the payments.
Other examples of using the toolkit can include:

• An application that lets merchants or enterprises pay their suppliers, or manage affiliate networks
• Applications to enable property owners to collect rental payments from tenants
• With a mult-merchant marketplace, a simple payroll app enables employee salary payments in multiple countries
• ...

As you can see, the toolkit's support of the Adaptive Payments APIs can easily enable all of these usecases.

Where to find more info
Please look at the sample code provided in the samples directory. The AdaptiveRequests.java class in AdaptiveSample and AdaptiveSampleFnAPI shows how to use the helper classes to send and receive requests. The PicMart sample app provides a simple example of how the Parallel Payment can be used in a Photo Printing app that let's users to buy prints of the pictures from Picasa Album of the photographer. This sample app uses the Picasa APIs to fetch the album and picture information from Picasa.

To learn more about the PayPal X Toolkit for App Engine, please visit: http://code.google.com/p/paypalx-gae-toolkit/ and to learn more about Adaptive Payments, please visit: https://www.x.com/community/ppx/adaptive_payments. You can find a lot of resources for developers like documentation, technical spec, sample apps, code, sdks, technical forums, technical support, etc.. on PayPal X Developer Network web site (https://www.x.com).
Posted by Praveen Alavilli (@ppalavilli), PayPal X Developer Network.