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.

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>
    <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">
            <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.elasticpath.paymentgateways</groupId>
            <artifactId>ep-payment-gateway-google-checkout</artifactId>
            <version>6.5.1-SNAPSHOT</version>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>com.extension.mypaymentgateway</groupId>
            <artifactId>my-payment-gateway</artifactId>
            <version>1.0-SNAPSHOT</version>
            <scope>runtime</scope>
        </dependency>
.....

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.

1. In the CM Client, open the Configuration activity.
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. Open the Configuration activity.
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.

Many payment gateways issue a certificate file to the merchant and require them to use it in the client code. For example, CyberSource has two properties. One is keysDirectory, which denotes the location of the certificate files. The other is merchantID, which is 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.

For example, in the case of CyberSource, if the key resides in /var/ep/conf/resources/payment/cybersource/ekkontest.p12:

• set keysDirectory for the payment gateway to conf//resources//payment//cybersource
• set merchantID for the payment gateway to ekkontest
• and set the certificatesDirectory setting to /var/ep.

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.