Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Creating a Payment Gateway

Creating a 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


When implementing a payment gateway, you will typically want to extend one of the abstract SPI classes available in the payment-gateway-connectivity-api jars, but if that is not practical it is also possible to 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.


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 {
    public List<String> getSupportedCardTypes() {
        return null;  //To change body of implemented methods use File | Settings | File Templates.
    public String getPluginType() {
        return null;  //To change body of implemented methods use File | Settings | File Templates.
    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 occured 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, you need to make the payment gateway factory aware of it. In your Core extension, you will need to 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"/commerce-legacy/>
    <bean id="paymentGatewayFactory" class="com.elasticpath.domain.payment.impl.PaymentGatewayFactoryImpl">
        <property name="settingsReader" ref="settingsService"/commerce-legacy/>
        <property name="giftCertificateTransactionService" ref="giftCertificateTransactionService"/commerce-legacy/>
        <property name="gatewayClasses">

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

<!--         Payment Gateways START -->

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 the CM, click on 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 on 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 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;


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.