Payment Processing

Elastic Path offers two types of payment options: credit cards and gift certificates. 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 a Demo (Null) gateway for use during development.

Each processor has its own requirements for setup and configuration, so you will need to refer to the developer documentation for your credit card processor for more information.

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

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

Creating Payment Gateway

The Elastic Path framework includes a payment-gateway-connectivity-api jar which includes all the necessary interfaces and classes required to implement a new payment gateway. They include:

• AbstractPaymentGatewayPluginSPI
• AbstractCreditCardPaymentGatewayPluginSPI
• PaymentGatewayPluginManagement

To use this jar in your new payment gateway project, you can reference the following maven dependency

<groupId>com.elasticpath</groupId>
<artifactId>ep-payment-gateway-connectivity-api</artifactId>
<version>7.0.0-SNAPSHOT</version>

When implementing a payment gateway, extend one of the abstract SPI (Service Provider Interface) classes available in the payment-gateway-connectivity-api jars. Alternatively, you can implement the PaymentGatewayPluginInvoker interface directly.

In addition to the payment gateway capabilities implemented by the AbstractCreditCardPaymentGatewayPluginSPI, the PaymentGatewayCapability interface can be extended and implemented to add various capabilities specific to your custom gateway.

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

• CheckEnrollment

  Used to determine whether or not a credit card account has been enrolled in a 3D secure service.

• validateAuthentication

  Used to verify the card holder’s authentication after they have been redirected back to your site from the processor’s verification site

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

public class MyPaymentGatewayImpl extends AbstractCreditCardPaymentGatewayPluginSPI {
    @Override
    public List<String> getSupportedCardTypes() {
        return null;  //To change body of implemented methods use File | Settings | File Templates.
    }
    @Override
    public String getPluginType() {
        return null;  //To change body of implemented methods use File | Settings | File Templates.
    }
    @Override
    public Collection<String> getConfigurationParameters() {
        return null;  //To change body of implemented methods use File | Settings | File Templates.
    }
}

Error Handling

When a problem occurs while executing a method on a PaymentGateway, an exception is thrown to inform the client. All vendor-specific problems should be consumed and reported as one of the following standard exception types:

• PaymentGatewayException

  Indicates that the payment processor has failed to process a request. For example, an internal error or communication failure has occurred.

• CardErrorException

  An unspecified error has occurred in processing the card information. This exception is thrown when there is a problem with the card data and not with the payment processor itself.

• CardExpiredException

  The card being processed has expired.

• CardDeclinedException

  The card being processed was declined. For example, the card has insufficient credit for the purchase.

• InsufficientFundException

  The payment method was declined due to insufficient funds

More exceptions can be found in the com.elasticpath.plugin.payment.exceptions package in the payment-gateway-extension-point project.

Configuring the Payment Gateway Factory

To use your new payment gateway, make the payment gateway factory aware of it. In your Core extension, override the paymentGatewayFactory bean definition in the service.xml file in your Core extension project. Add an entry to the gatewayClasses set property with the fully qualified class name of your payment gateway plugin implementation:

<bean id="paymentHandlerFactory" class="com.elasticpath.domain.payment.impl.PaymentHandlerFactoryImpl">
   <property name="elasticPath" ref="elasticPath"/>
</bean>
<bean id="paymentGatewayFactory" class="com.elasticpath.domain.payment.impl.PaymentGatewayFactoryImpl">
   <property name="settingsReader" ref="settingsService"/>
   <property name="giftCertificateTransactionService" ref="giftCertificateTransactionService"/>
   <property name="gatewayClasses">
      <set>
            <value>com.elasticpath.service.payment.gateway.impl.NullPaymentGatewayPluginImpl</value>
            <value>com.elasticpath.service.payment.gateway.impl.ExchangePaymentGatewayPluginImpl</value>
            <value>com.elasticpath.service.payment.gateway.impl.GiftCertificatePaymentGatewayPluginImpl</value>
            <value>com.elasticpath.service.payment.gateway.impl.MyPaymentGatewayImpl</value>
      </set>
   </property>
</bean>

A maven dependency also needs to be added to the extension-core pom.xml file for the new payment gateway:

<!-- Payment Gateways START -->
<dependency>
   <groupId>com.extension.mypaymentgateway</groupId>
   <artifactId>my-payment-gateway</artifactId>
   <version>0-SNAPSHOT</version>
   <scope>runtime</scope>
</dependency>
.....

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, and then configure your store to use it.

1. In Commerce Manager, click the Configuration icon.
2. Under Payment Methods, click Payment Gateways.
3. Click Create Gateway.
4. Enter the payment gateway name.
5. Select the gateway implementation the Type list.
6. Set any required properties.
7. Click Save.

To use the new payment gateway in your store:

1. Click the Configuration icon.
2. Click Stores.
3. Select the store in the list and click Edit Store.
4. Click the Payments tab.
5. Select the payment gateway in the Credit Card Payment Gateway list.
6. Configure the options for enabling the CCV (Credit Card Verification) value, saving credit card numbers, and the supported card types.
7. Click Save.

The Payment Gateway Certificate File

Many payment gateways issue a certificate file to the merchant and require them to use it in the client code. These gateways may have properties to denote the location of the certificate file(s) and the name of the certificate file.

There is a system wide setting that is used for the base directory of all the payment-related certificate key files. The setting resides in COMMERCE/SYSTEM/PAYMENTGATEWAY/certificatesDirectory, and can be changed through Commerce Manager’s configuration perspective. When setting the payment gateway configurations in the Commerce Manager, the path to the certificate should be relative to the base directory mentioned by the above setting.

The payment gateway implementation class can access that base directory through a protected method on AbstractPaymentGatewayPluginSPI:

/**
 * Gets the path prefix for the payment gateway certificate files.
 *
 * @return the path prefix
 */
protected String getCertificatePathPrefix() {
        return certificatePathPrefix;
}

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. See 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.