Payment gateways

Payment gateways provide an interface to the system which provides payment processing. A payment type is passed to the payment gateway and the gateway executes the payment transaction with the payment system. One payment type is associated with each payment gateway.

When creating and configuring payment methods in EPiServer Commerce, you have the following options:

• Using a built-in payment gateway
• Creating multiple instances of the same gateway but with different configuration
• Creating your own custom payment gateway

The various implementation options are described below..

Classes referred to here are available in the following namespaces:

• Mediachase.Commerce.Orders - contains IShippingGateway, Payment types

Gateway properties

These are the gateway properties to be configured when using the various options:

• Id the system-assigned unique identifier for the payment gateway.
• Name the name to be displayed to the user.
• Description a description that can be displayed to the user.
• System Keyword the unique name for each instance of the gateway; new non-unique keywords will not save to the database. This is not be editable after a gateway is initially created.
• Language allows a specific language to be specified for the payment gateway.
• Class Name name of the gateway class to be associated with the payment.

Using a built-in payment gateway

1. In Commerce Manager, go to the Administration tab and Order System/Payments/Language.
2. Select the built-in method to be used.
3. Configure the payment method. See the gateway properties definitions above.
4. Configure the Parameters tab of the payment method with details specific to the particular payment gateway. This interface provides fields dynamically based on the gateway.
5. Click OK.

Creating multiple instances of a gateway

1. Follow steps 4-6 of the Create Custom Payment Gateway directions below.
   Note that you should be able to copy the control associated with the existing implementation of the payment gateway (from the ManagementConsole/ConsoleManager/App/Order/Payments/Plugins/ existing gateway folder name also known as system keyword) and simply give the control class file (.ascx.cs) a unique name. Use a new folder name that corresponds to the System Keyword that will be used in step 4.
2. In Commerce Manager, go to the Administration tab and Order System/Payments/Language.
3. Click New.
4. Configure the payment method. See the gateway properties definitions above. Click OK.
5. Re-open the payment method from the payment method list.
6. Go to the second tab and set any configuration information required for the particular implementation of this gateway.
7. Click OK to save the new information.

Creating a custom payment gateway

1. Create a separate project in the solution to store custom business logic implementations for your application, if this has not been done.

2. Create a class in this project that inherits from the abstract class AbstractPaymentGateway. This base class has only has one property Settings, and one method, ProcessPayment().

The Settings property is a dictionary type that allows other information regarding the gateway to be stored, for example web service authentication details for connecting to the payment provider or an indicator whether the payment provider call is for authorization or payment processing. ProcessPayment is the method used to contact the payment processing system and process payments.

Example: signature for the ProcessPayment method

bool ProcessPayment(Payment payment, ref string message);

Provide implementation for the ProcessPayment method to execute the payment transaction you need. Look at the BusinessLayer/OrderSystem/PaymentGateways/ICharge/IChargeGateway.cs class file for an example implementation.

3. Create an admin config user control. This is used to provide an interface in the Commerce Manager for the second tab of the Payment Method edit screen. This tab will not be available until after the information on the first tab for a new method is saved for the first time.

• The new ascx needs to be added to a new folder in the ManagementConsole/ConsoleManager/App/Order/Payments/Plugins/Folder, named the same as the System Keyword to be set to below.
• The .ascx file will be named ConfigurePayment.ascx.
• The control must implement the IGatewayControl interface and inherit from OrderBaseUserControl. Look at ManagementConsole/ConsoleManager/Apps/Order/Payments/PlugIns/Authorize/ConfigurePayment.ascx for an example of how to implement this.
• LoadObject() this method at a minimum should contain code as below.

Example: minimum code for LoadObject() method

public void LoadObject(object dto) 
                        { 
                          _PaymentMethodDto = dto as PaymentMethodDto; 
                        }

4. Re-compile the solution.

5. Copy the .dlls associated with the project where the payment gateway is implemented into the bin folders of both the Commerce Manager and Public websites.

6. In Commerce Manager, go to the Administration tab and Order System/Payments.

7. Click New.

8. Enter information about the method being added:

• Make sure to enter a System Keyword that corresponds with the folder added in the ManagementConsole/ConsoleManager/Apps/Order/Payments/PlugIns/ folder (step 4) to contain the admin control.
• See the gateway properties description above for information on the fields on the first tab.
• Select the new gateway from the drop-down list.
• Make sure to set IsActive to "Yes" if you intend to start using the payment method. When the information has been added to the first tab, click OK to save the information.

9. Re-open the payment method from the payment method list.

10. Go to the second tab and set any configuration information required for the particular implementation of this gateway.

11. Click OK to save the new information.

Adding payment types

If you need a payment type that does not correspond to one of the payment types built into ECF, you can extend the built-in OtherPayment payment type with whatever meta fields you need.

Modifying OtherPayment payment type

1. In Commerce Manager, go to the Administration tab and Order System/Meta Classes.
2. Select Order Form Payment from the Element drop-down list.
3. Select Other Payment from the Type drop-down list.
4. Select the meta fields that you need to associate with the meta class.
5. If you need a field that is not available:
   - Click on the Meta Fields node.
   - Click New.
   - Add the field properties and click OK.
   - Repeat these steps as needed.

Adding meta fields to payment types

If you are implementing your own gateway, you may want to add meta fields to one of the built-in payment types for instance CreditCardPayment, to store custom information. This can be done through Commerce Manager. See the steps under modifying the OtherPayment payment type, and use the same approach with the meta class you need to add meta fields to.