WSO2 ESB Business Service Adapter - Part 1 ( Integration with PayPal WS API )

Applies To

Contents

• Introduction
• Abbreviations
• Overview
• Interaction of between Client, WSO2 ESB and PayPal WS API
• UI component of WSO2 ESB - PayPal CBA
• Implementation and usage of the PayPal Business Adapter
• Advantages of the PayPal Business Adapter
• Summary
• References
• Resources

Introduction

Firstly, this article will present a brief overview of the integration of WSO2 ESB with the WS API provided by PayPal and this was our first attempt for such an integration. The purpose of this integration is to provide a convenient interface for PayPal WS API within the WSO2 ESB, so that the users of the WSO2 ESB can easily and readily perform transactions with PayPal. Given the fact, the exponential popularity gained by the WSO2 ESB in the Service Oriented Architecture realm since its inception, this can be proven to be an invaluable feature for its users.

WSO2 Carbon is the development framework and run-time for all WSO2 SOA based middleware such as WSO2 ESB, it offers most of the imperative functionality along with a set of core services that are common across all the WSO2 middleware. The WSO2 Carbon platform is based on OSGi, providing better modularity and componentization for your SOA based solutions.

WSO2 ESB 3.0.0, a part of the WSO2 middleware platform stack that provides the mediation capabilities and is a lightweight, flexible, extensible and easy-to-use Open Source ESB available under the Apache Software License v2.0. WSO2 ESB allows simple and convenient way of configuring message routing, virtualization, intermediation, transformation, logging, task scheduling, load balancing, fail-over routing, event brokering and much more. WSO2 ESB's runtime has been designed to be completely asynchronous and is based on the Apache Synapse mediation engine.

You can find more about the WSO2 ESB 3.0.0 here

PayPal is an online payment service provider that serves payments and fund-transfers to be made over the Internet and acts as an alternative to conventional methods such as checks and money orders.
PayPal, like most of the other solution providers, offers a testing environment called the PayPal Sandbox as a play ground for its external developers, and it is a replica of the live PayPal site, except the fact that no real money exchanges hands. The Sandbox allows external developers/organizations to test their entire integration with the PayPal WS APIs before handing over transactions to the live PayPal environment. Typically, these APIs in the sandbox environment provides operations to create and manage test accounts, and view emails and API credentials for those test accounts. There are several methods to integrating PayPal services with your B2B web applications:

Figure 1: Different ways of integrating an application with PayPal in a B2B environment.

Table 1: Ways of integrating with PayPal.

When using the PayPal API, there are two interfaces provided for it. The developers can make the most appropriate selection to suite their style of development and environment:

• REST/Name-Value Pair (NVP) style interface
  
  
  The requests and responses are based on simple HTTP. This interface is suitable for those who prefer more lightweight, script-based development.
• SOAP style interface
  
  
  The requests and responses are based on SOAP. This interface is suitable for those who prefer object-oriented development.

Fore more details about all API endpoints for PayPal sandbox and live environments for NVP and SOAP.

Abbreviations

Table 2: Terms and abbreviations.

Overview

WSO2 ESB comes with a diverse range of handful mediators to process messages. When the existing core mediators comes in short for your needs, you can write your own tailor made mediator to implement your specific business requirements, you heard me right, it comes with extensibility. Your custom mediators can be simply plugged into WSO2 ESB. After successfully binding them to ESB, they will operate as first class citizens as same as the core mediators that are bundled with the ESB.

One method of implementing a WSO2 CBA is, to use the extensibility feature given by the WSO2 ESB for creating custom mediators to suit for specific business requirements. The WSO2 ESB PayPal CBA, is one such CBA that is been provided by the WSO2 ESB to encapsulate the service operations offered by the actual PayPal WS API. It acts as an intermediary between the PayPal WS API endpoint and the client application as shown in Figure 3. Though, there are several methods of integrating an external system with the PayPal, this article is specifically focusing on PayPal API integration method using SOAP.
Internally, WSO2 ESB PayPal CBA uses a AXIS2 service client to perform it's operations. Generally, one or more PayPal CBAs are exposed as a proxy service of the ESB, which the end-user application invokes.

The PayPal SOAP API service is made secured to assure that only authorized PayPal members use it. To invoke a particular operation in the PayPal WS API, it requires certain level of credential information ( header details of the message ) along with the input values ( payload of the message).

Figure 2: The structure of a PayPal SOAP request envelope.

A SOAP request structure of PayPal WS API looks like as follows:

<SOAP-ENV:Envelope ... >
<SOAP-ENV:Header> 
	<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”> 
		<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”> 
			<Username>username<Username/> 
			<Password>password<Password/> 
			<Signature/>     
			<Subject/> 
		<Credentials/> 
	<RequesterCredentials/> 
<SOAP-ENV:Header/> 
<SOAP-ENV:Body> 
	<specific_api_operation_name_Req xmlns=”urn:ebay:api:PayPalAPI”> 
		<specific_api_operation_name_Request> 
			<Version xmlns=urn:ebay:apis:eBLBaseComponents”>version_number<Version/> 
			<required_or_optional_fields xsi:type=”some_type_here”>data<required_or_optional_fields/> 
		<specific_api_operation_name_Request/> 
	<specific_api_operation_name_Req/>
 
<SOAP-ENV:Body/> 
<SOAP-ENV:Envelope/>

Table 3: Elements of PayPal SOAP request envelope.

Each PayPal CBA in a proxy or a sequence is configured to invoke a specific operation in the PayPal WS API, the header and payload of the outgoing message are constructed by specifying either XPath expressions or source values as a part of the configuration, which extracts the required information from the incoming message context from the client. Based on the configuration provided, the CBA will construct a SOAP request, that is compliant with the actual PayPal WS API and mediates the request to that endpoint. Similarly, the response received from the PayPal WS can be set as a property in the message context or as a part of the response sent back to the client via XPath expressions.

Interaction of between Client, WSO2 ESB and PayPal WS API

Figure 3: Shows the interaction between the Client, WSO2 ESB and PayPal WS API.

The message mediation can be briefed as follows,

• The WSO2 ESB's PayPal proxy service accepts a SOAP message, which is non-compliant with the PayPal WS API.
• The WSO2 ESB's PayPal proxy service will consist of one or more PayPal CBAs.
• Each PayPal CBA is configured to invoke a specific operation in the PayPal WS API.
• PayPal CBA will then constructs a SOAP message, which is compliant with the PayPal WS API and dispatches to the PayPal WS endpoint as a request.
• The output received form the PayPal WS endpoint will be processed based on the configuration.

Configuration details of the PayPal Business Adapter

Like most other mediator that comes with the WSO2 ESB, PayPal CBA involves certain level of configuration to process the incoming SOAP request. These configuration elements are described as follows:

<syn:paypal>
   <syn:credentials>
      <syn:username  xpath="username_xpath" | source-value="username_string" />
      <syn:password  xpath="password_xpath" | source-value="password_string" />
      <syn:signature xpath="signature_xpath" | source-value="signature_string" />
      <syn:subject   xpath="subject_xpath" | source-value="subject_string" />
   </syn:credentials>
   <syn:operation name="operation_name" currency="currency_code">
      <syn:inputs>
         <syn:input name="input_name" (source-xpath="input_xpath" | source-value="input_string") /> *
      </syn:inputs>
      <syn:outputs>
         <syn:output target-key="output_property_string" | source-xpath="response_xpath" target-xpath="msg_context_xpath" /> *
      </syn:outputs>
   </syn:operation>
</syn:paypal>

Table 4: Configuration details of PayPal business adapter.

Note: The version number is not required as an input from the user, because PayPal BA will be configured to support only a given PayPal API version (e.g: 61.0).

Samples of Synapse configurations for PayPal CBAs:

Example 1: Using XPath expressions for the configuration. The following examples shows the simplest configuration to invoke the 'GetBalance' operation in the PayPal WS API, this operation returns the standing balance amount of the user. Here, the user has to provide the credential details such as username, password and optional signature and no input is required. The response received from the PayPal WS API will be stored in a Synapse property called 'get-bal-response-key' and later, this key can be use to process the response content.

<syn:paypal>
   <syn:credentials>
      <syn:username xpath="//ns:login/username" xmlns:ns="uri:wso2:paypal" />
      <syn:password xpath="//ns:login/password" xmlns:ns="uri:wso2:paypal" />
      <syn:signature xpath="//ns:login/signature" xmlns:ns="uri:wso2:paypal" />
      <syn:subject xpath="//ns:login/subject"
 xmlns:ns="uri:wso2:paypal" />
   </syn:credentials>
   <syn:operation name="GetBalance" currency="USD">
      <!--
	  <syn:inputs>
         <syn:input name="DetailLevel" source-xpath="//getBalance/detailLevel" />
         <syn:input name="ErrorLanguage" source-xpath="//getBalance/errorLang" />
      </syn:inputs>
	  -->
      <syn:outputs>
         <syn:output xmlns:urn="urn:ebay:api:PayPalAPI" source-xpath="//urn:GetBalanceResponse" target-xpath="//response" />
      </syn:outputs>
   </syn:operation>
</syn:paypal>

Possible soap request body could be like,

   <SOAP-ENV:Body>

   <!-- this contains the credential information -->
   <ns:login xmlns:ns="uri:wso2:paypal">
      <ns:username>username_biz_api1.wso2.com</ns:username>

      <ns:password>12sds3sds69211</ns:password>
      <ns:signature>AaNvupC2HsVPs-d5iU9.YgFyjltMAh4w9w9d7jqGMZAIuMO8mvGVtKzd</ns:signature>
	  <ns:subject>[email protected]</ns:subject>
   </ns:login>

   <getBalance>
	  <detailLevel>full</detailLevel>
	  <errorLang>eng_us</errorLang>
   </getBalance>
   
   <!-- this is where the response received from the PayPal WS will be set-->
   <response></response>
   </SOAP-ENV:Body>
  

Example 2: In this example, the required input values are directly provided in the configuration. The following examples shows the simplest configuration to invoke the 'GetBalance' operation in the PayPal WS API, this operation returns the standing balance amount of the user. Here, the user has to provide the credential details such as username, password and optional signature and no input is required. The response received from the PayPal WS API will be stored in the Synapse message context as an XML element. Later, this XML element can be use to process the response content.

<syn:paypal>
   <syn:credentials>
      <syn:username source-value="username_biz_api1.wso2.com" />
      <syn:password source-value="12sds3sds69211" />
      <syn:signature source-value="AaNvupC2HsVPs-d5iU9.YgFyjltMAh4w9w9d7jqGMZAIuMO8mvGVtKzd" />
	  <ns:subject>[email protected]</ns:subject>
   </syn:credentials>
   <syn:operation name="GetBalance" currency="USD">
      <syn:inputs>
         <syn:input name="DetailLevel" source-value="full" />
         <syn:input name="ErrorLanguage" source-value="eng_us" />
      </syn:inputs>
      <syn:outputs>
		 <syn:output target-key="get-bal-response-key" />
      </syn:outputs>
    </syn:operation>
</syn:paypal>

These are examples only to give you an idea of how the configuration might look in the WSO2 ESB. It doesn't mean that, doing all this configuration is the only way you can go forward. To make life submissive and convenient, an UI component has been shipped with the WSO2 ESB for the Paypal CBA, where the user has to simply provide the necessary details without much of a hazel. The next section will show how the UI can be used for the configuration.

UI component of WSO2 ESB - PayPal CBA

The UI component contains the necessary controls to do the required configuration of a PayPal CBA. The following functionality is been provided for the users to make the configuration more convenient.
- User has the capacity to select a desired operation.
- Configure the credential details, inputs and outputs using either X-path expressions or values. Next section shows some screen shots of the PayPal CBA configuration console in the WSO2 ESB.

Figure 4: Shows the sequence configuration UI of the WSO2 ESB.

Figure 5: Shows the PayPal CBA configuration UI of the WSO2 ESB.

A - Section providing the credential information required to invoke an operation in the PayPal WS API.


B - Section providing the set of operations in the PayPal WS API, that can be invoked in the form of a drop-down list and they are pre-configured.


C - Section providing the input configuration information. The input details appearing on this section varies based on the selected operation (Section - C).


D - Section providing the output configuration information to be added (see Figure 4 and Figure 5).

Figure 6: Shows an example of a PayPal CBA configuration using XPath expressions.

Figure 7:Shows another example of a PayPal CBA configuration using literal values directly.

Implementation and usage of the PayPal Business Adapter

As mentioned before, this is available as a feature of the WSO2 ESB. If it's not already a part in your WSO2 ESB, please install the feature (WSO2 ESB Management Console --> Configure --> Component Manager --> Available Features --> Find new features or updates to installed features in available repositories). Once you have the feature bundles related to the PayPal installed on your WSO2 ESB instance, you can proceed with the followings.

To provide you a quick start, lets look at how to create and configure a sequence to and expose it over an WSO2 ESB proxy service. I'll use the 'GetBalance' operation on the PayPal WS API for demonstration purposes.

• Firstly, we need to create a message sequence containing one or more PayPal business adapters. Here you need to configure for a desired operation you are going to invoke. In this case it's the 'GetBalance' operation. Use the UI to design the sequence. Let us call this 'PayPal_Sequence'

  Figure 8: Example of a PayPal CBA configuration for 'GetBalance' operation.

  

• One of the easiest ways of making use of this sequence, is to create a proxy service in the WSO2. So now, lets add a proxy service called 'PayPal_Proxy'. To create the proxy, select WSO2 ESB Management Console --> Manage --> Services --> Add --> Proxy Service --> Custom Proxy and configure the proxy to use the message sequence that we just created by importing 'PayPal_Sequence' from the In Sequence Options.

  Figure 9: Creating a custom proxy.

  

  Figure 10: Associating the the PayPal CBA configuration for 'GetBalance' operation with the custom proxy.

  

• Now, from the client's end, lets send a SOAP request to the PayPal proxy service that we created in WSO2 ESB. The body of this SOAP message should contain all the information that are expected by the XPath expressions, if any, within the PayPal sequence configuration.

     <SOAP-ENV:Body>
  
     <!-- this contains the credential information -->
     <ns:login xmlns:ns="uri:wso2:paypal">
        <ns:username>username_biz_api1.wso2.com</ns:username>
  
        <ns:password>12sds3sds69211</ns:password>
        <ns:signature>AaNvupC2HsVPs-d5iU9.YgFyjltMAh4w9w9d7jqGMZAIuMO8mvGVtKzd</ns:signature>
  	  <ns:subject>[email protected]</ns:subject>
     </ns:login>
  
     <ns:ope>
  	  <ns:detail-level>requested detail level value</ns:detail-level>
  	  <ns:return-all-currency>requested return all currency value</ns:return-all-currency>
     <ns:/ope>
    

• Based on your configuration, the response received is either set as a property into the Synapse' message context or as a part of the SOAP request that was sent by the end-client to the WSO2 ESB.

Advantages of the PayPal Business Adapter

• Simplicity - Involves only a simple set of configurations.
• Flexible - Can process and manipulate SOAP request messages, which contains details to invoke operations in the PayPal WS API and that are non-complaint with the PayPal WS interfaces.

Summary

In summary, WSO2 ESB attempts to offer a wide range of robust features and to evolve its existing capabilities for its clients to make things more intuitive with less amount of cost. It is apparent that more and more business to business application are getting involved with e-commerce business service providers like PayPal and the capacity to provide an API to communicate with the PayPal WS API within the ESB can become a very handy feature for the commercial world.

References

1. Table 1: Ways of integrating with PayPal


2. Figure 2: PayPal SOAP API Overview


3. The SOAP request structure of PayPal WS API: A
SOAP request structure of PayPal WS API


4. Table 3: Elements of PayPal SOAP request envelope

Resources

1. WSO2 Carbon
2. WSO2 ESB 3.0.0
3. Apache Synapse
4. PayPal Sandbox Developer Environment