When customizing Elastic Path the most common form of Java-code level customization is integration with an external fulfillment service.  This integration can take many forms, depending on your architecture:  SOAP or Restful Web services, JMS messages, flat files, RMI calls, etc.

Such integration is always tricky, and usually painful.  It doesn’t have to be.

The Elastic Path checkout architecture has become much more modularized, making it very easy to implement a new CheckoutAction where your fulfillment integration can start, but you still have to implement the code to make the call.

This is where Apache Camel can make your life much easier, by abstracting the plumbing of such a call from your Java code.

This post will show how you can use Apache Camel and Apache CXF to call an external SOAP-based fulfillment Web service using a few simple lines of code in your CheckoutAction.

First, a couple of assumptions:

• You have a WSDL for the Web service
• You have created an extension core project to extend the Elastic Path Core project
  

Now, create a new Maven project that will generate the Web service code and expose it to your application via a JAR file.  The following pom.xml file can be used as a starting point:

This pom assumes you have placed the Web service’s WSDL file in the src/main/resources/wsdl folder under your project folder.  It uses the Apache CXF plugin to generate the sources from the WSDL.

Executing “mvn install” will then create the JAR file, containing the classes and the WSDL file, and install it into your local Maven repository.

Add a dependency on this library in your core extension project.

Next, in your extension core project, add a couple other new dependencies:

Now, implement a type converter class that will be used by Camel to convert the Elastic Path Order object to the object used by the Web service:

Then add a file called TypeConverter (with no extension) to the src\main\resources\META-INF\services\org\apache\camel in your core extension project.  It should contain a single line, the fully qualified class name of your converter.  For example:

Next implement a Camel Route builder class that will route the EP Order to the Web service:

This class defines a Camel endpoint called “direct:startorderfulfillment”.  It first converts the data sent to the endpoint, which should be an EP Order object, to the Order object expected by the fulfillment Web service.  Camel is smart enough to find the type converter you implemented earlier and uses that to do the conversion.  Finally it sends that converted object to the Web service.  It refers to the WSDL file from the class path, which is provided by the client project created earlier.

The Web service’s path, service name, port name and class name will be dependent on your situation.

Now implement your CheckoutAction to send the EP order to Camel:

This class sends the EP Order object to the Camel endpoint called “direct:startorderfulfillment”, which we defined in the route builder class we implemented earlier.

Finally, add the following Spring bean configuration in your core extension project’s plugin.xml file:

Make sure to add http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd to the xsi:schemaLocation attribute.

The <package> element must specify the name of the package where your Camel route builder class is implemented.  Camel will automatically pick it up and configure it.

That’s it.  Compile and run your storefront and watch the orders pile up.

The really great thing about this design is that you can implement any endpoint you wish in the Camel route builder and never need to modify your checkout service.  Camel includes components for sending to JMS queues, RMI services, flat files, etc.
In your route, you can also include any number of endpoints, whether for logging/auditing purposes, messaging multiple services, etc.

You can also configure the routes in your Spring configuration file without having to implement a custom route builder class, but that’s a personal preference.

Enjoy the Camel ride.

Elastic Path offers several types of payment options: credit cards, gift certificates, PayPal, and Google Checkout. The specific implementation of a payment type is referred to as a payment gateway.  New payment types can be added, but a common requirement is to support a new credit card processor. This is the external service used to process your credit card transaction requests. Out of the box, Elastic Path includes support for CyberSource, Verisign, and Authorize.net, as well as a dummy gateway for use during development.

This post will show how to add a credit card payment gateway to your implementation.

The most difficult aspect is understanding the processor's requirements and communication protocol. Every processor has its own requirements, so you will need to fefer to the developer documentation for your credit card processor for more information on your processor.

There are several issues to consider when implementing a gateway for a credit card processor:

• Pre-authorization
• Settlements, referred to as Captures
• Refunds
• Voiding transactions
• Supported credit cards

The Elastic Path framework includes a PaymentGateway interface and a CreditCardPaymentGateway interface, as well as corresponding implementations that cover offer support for all credit card transactions.

The CreditCardPaymentGateway also supports 3D Secure authentication, such as Verified-By-Visa and SecureCard from MasterCard with the following methods:

The Elastic Path storefront already makes use of these methods. Simply implement them to take advantage of the services.

Extend the AbstractCreditCardPaymentGatewayImpl and create your credit card payment gateway class as in the following code:

@Entity
1) @DiscriminatorValue("paymentGatewayMyProcessorNameHere")
public class MyProcessorNameHerePaymentGatewayImpl extends AbstractCreditCardPaymentGatewayImpl implements CreditCardPaymentGateway {
 
 
2)  private String type = "paymentGatewayMyProcessorNameHere";
 
@Basic
@Column(name = "TYPE", insertable = false)
public String getType() { return type; }
 
protected void setType(final String type) { this.type = type; }
 
 
3)  protected Set<String> getDefaultPropertyKeys() {
                      Set<String> defaultPropertyKeys = new TreeSet<String>();
                      defaultPropertyKeys.add("merchantId");
                      defaultPropertyKeys.add("username");
                      defaultPropertyKeys.add("password");
                      return defaultPropertyKeys;
      }
 
 
4)  public void preAuthorize(final OrderPayment payment, final Address billingAddress) {
 
 
5)                  String merchantId = getPropertiesMap().get("merchantId").getValue();
 
 
6)                  OrderShipment orderShipment = payment.getOrderShipment();
int number = 0;
for (OrderSku orderSku : orderShipment.getShipmentOrderSkus()) {
      addItemToRequest(request, number, orderSku);
      number++;
}
 
 
7)                  Order order = orderShipment.getOrder();
addOrderDetailsToRequest(order);
 
                      ...
 
      }
 
8)  public void capture(final OrderPayment payment) {
                      ...
      }
 
9)  public void sale(final OrderPayment payment, final Address billingAddress) {
                      ...
      }
 
10)  public void refund(final OrderPayment payment, final Address billingAddress) {
                      ...
      }
 
11)  public void reversePreAuthorization(final OrderPayment payment) {
                      ...
      }
 
12)  public void voidCaptureOrCredit(final OrderPayment payment) {
                      ...
      }
 
13)  public PayerAuthenticationEnrollmentResult checkEnrollment(
final ShoppingCart shoppingCart, final OrderPayment payment) {
                      ...
      }
 
14)  public boolean validateAuthentication(final OrderPayment payment, final String paRes) {
                      ...
      }
}

1. The DiscriminatorValue must be set to the value specified for the gateway's type property.
2. The type property must be set to a value unique among all payment gateways.
3. getDefaultPropertyKeys must implemented to return a Set of property keys. The Set can be empty if there are no properties.
4. The preAuthorize method must be implemented to make a pre-authorization transaction request to the payment processor.
5. Properties can be accessed from the gateway's properties map.
6. Access the shipment details through OrderPayment's orderShipments property.
7. Access the order details through the order property of OrderPayment's orderShipment.
8. The capture method must be implemented to make a settlement transaction request to the payment processor.
9. The sale method must be implemented. Its purpose is to perform a combination of pre-authorization and capture at the same time. Some processors offer such a transaction. If not, then this method could make pre-authorization and capture transaction requests
   However, there is currently no logic using it in Elastic Path. So, it can be ignored
10. The refund method must be implemented to make refund transaction requests to the processor.
11. The reversePreAuthorization method must be implemented to make transaction requests to the processor that reverse the pre-authorization.
    Some credit card processors support this feature, but others do not. Refer to your processor's developer documentation for more information.
12. The voidCaptureOrCredit method must be implemented to make transaction requests to the processor that void a previous capture or credit transaction.  Void transactions typically only work on transactions made the same day.
13. The checkEnrollment method must be implemented to make requests to the processor to determine whether or not a credit card has been enrolled in the 3D Secure program.
14. The validateAuthentication method must be implemented to make requests to the processor to verify a 3D Secure payment response after the customer has authenticated themselves on the processor's 3D Secure server.

Error Handling

Errors occasionally happen. With credit cards, they can frequently happen. Elastic Path implements several exceptions to account for the most common problems. These exceptions should be thrown from the preAuthorize or capture methods when appropriate.

To add your own exceptions, extend one of the following exception classes, and throw it as appropriate:

Configuring the Payment Gateway Factory

In order to use your new credit card gateway, you'll need to make the payment gateway factory aware of it. The paymentGatewayFactory bean defined in the domainModel.xml file must include a new entry.

<bean id="paymentGatewayFactory"

      class="com.elasticpath.domain.payment.impl.PaymentGatewayFactoryImpl">

      <property name="paymentGateways">

                      <map>

                                      ...

                                                <entry key="paymentGatewayMyProcessorNameHere">

                                                                <value>

com...MyProcessorNameHerePaymentGatewayImpl

</value>

                                                </entry>

                                      ...

                      </map>

      </property>

</bean>

The entry's key must be set to the payment gateway's type property that was specified in the implementation class.

Using the Payment Gateway

To use your new credit card gateway implementation, you will first need to create a new payment gateway configuration in the CM Client, and then configure your store to use it.

In the CM Client:

• Open the Configuration activity
• Select Payment Gateways
• Click Create Gateway
• Type in your gateway name
• Select your new gateway implementation the Type dropdown

To use the new payment gateway in your store:

• Open the Configuration activity
• Select Stores
• Edit your store
• Select the Payments tab
• Select your new Payment Gateway in the Credit Card Payment Gateway dropdown
• Choose the options for enabling the CCV value, saving credit card numbers, and the supported card types.

Caveats

Many processors will provide a testing infrastructure. Occasionally, this means a test merchant account, test card numbers, and possibly a different URL from what should be used in production.  Refer to your processor's development documentation to understand how to test it.  When moving to production, the first thing you will want to do is to test it. This means using a live credit card. There aren't many ways around this. However, you should have access to a console to manage your merchant account, and be able to cancel any transactions.