When creating and configuring payment methods in ECF, there are three components that need to be created or re-used as well as configured: Payment Types, Payment Gateways and Payment Methods.
Payment Types - Payment types are classes which contain the properties of a particular payment type. For example, a credit card payment type contains credit card number, card expiration date, card type, etc. All payment types inherit from the abstract class Payment. The most common payment types are already built-in to ECF: Credit card, cash card, gift card, and invoice. In addition, a generic OtherPayment type is included in ECF. Payment types are meta classes.
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 (e.g. PayPal). One payment type is associated with each payment gateway.
Gateway Properties - Here are explanations for some of the gateway properties:
- 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
Payment Methods - Payment methods contain information about the way the customer views a payment option and has a payment gateway associated with it.
There are several alternatives when setting up payment options for your site:
- Use one of the built-in Payment Gateways that are included with the ECF. This includes our integration with nSoftware which gives you access to over 50 of the top payment gateways in the U.S.
- Create multiple instances of the same gateway with different configuration. This would apply to a situation where you need to, for example, have two different payment setups with different account information for PayPal, especially for a multi-site implementation.
- Create and Integrate your own Payment Gateway. This gives you a very easy way to adapt capabilities and use any type of payment gateway around the world
1. In Commerce Manager, go to the Administrative tab and Order System/Payments/[Language] node.
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. Press OK.
6. 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 AKA 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.
7. In Commerce Manager, go to the Administrative tab and Order System/Payments/[Language] node.
8. Click the New button.
9. Configure the payment method. See the Gateway Properties definitions above. Click the OK button.
10. Re-open the payment method from the payment method list.
11. Go to the second tab and set any configuration information required for the particular implementation of this gateway. Press OK to save the new information.
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 AKA 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 Administrative tab and Order System/Payments/[Language] node.
3. Click the New button.
4. Configure the payment method. See the Gateway Properties definitions above. Click the OK button.
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. Press OK to save the new information.
1. If you haven't already, create a separate project in the solution to store custom business logic implementations for your application.
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. The ProcessPayment is the method used to contact the payment processing system and process payments. Here's the signature for the method:
3. 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.
4. 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 won't be available until after the information on the first tab for a new method is saved for the first time.
5. 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 is going to be set to in step 9].
6. The .ascx file will be named ConfigurePayment.ascx.
7. 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.
8. Further information on IGatewayControl methods. Again, a good example for these methods are found in .../ Authorize/ConfigurePayment.ascx:
SaveChanges() – This method has one parameter, which is a dto (PaymentMethodDto) containing the database information relating to the particular payment method being edited. It contains a PaymentMethod table row which contains the PaymentMethodId for the payment method. If the second tab payment parameters have already been saved for a payment method, the dto will also contain PaymentMethodParameterRow entries contained in the PaymentMethodDto.PaymentMethodParameter typed datatable to edit the properties associated with the payment method. If the second tab payment parameters have not been set and saved yet for the payment method (e.g. after the method is saved for the first time), the first save on this tab (by pressing the OK button while on either tab) will save the parameter settings to the database.
LoadObject() – This method at a minimum should contain the following code:
Note that _PaymentMethodDto is a member variable of type PaymentMethodDto.
9. Re-compile the solution.
10. Copy the .dlls associated with the project where the payment gateway is implemented into the bin folders of both the Commerce Manager and Public web sites.
11. In Commerce Manager, goto the Administration tab, Order System/Payments/[Language] node.
12. Click New button.
13. Enter information about the method being added.
14. 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.
15. See the gateway properties description above for information on the fields on the first tab.
16. Select the new gateway from the drop-down list.
17. Make sure to set IsActive to Yes if you intend to start using the payment method.
18. When the information has been added to the first tab, press OK to save the information.
19. Re-open the payment method from the payment method list.
20. Go to the second tab and set any configuration information required for the particular implementation of this gateway. Press OK to save the new information.
Note these directions do not contain details on how to display this information to the customer on the web site. For custom gateways, you'll need to implement your own method for displaying and saving payment information for this gateway. The simplest tool to use to retrieve payment option information is the PaymentMethodDto class. For saving customer payment information entered on the public site, look to the PublicLayer/FrontEnd2/Templates/Default/Checkout/CheckoutWizardModule.ascx and ..CheckoutPaymentModule.ascx controls.
Here is a downloadable example of a payment gateway. It contains a simple gateway that doesn't do anything but contains example code and comments to guide you in using the ECF payment APIs. It includes a configuration page (Parameters tab in the payment gateway definition) that has two simple parameters that can be saved and used in the simple gateway. Follow these steps to setup this example code:
1. Unzip the projects
2. In Visual Studio.NET, add these two projects to your ECF 5.1 solution (SDK or full source).
3. Add the following references from the B2CSampleSite bin folder:
- PaymentProviderExample.dll (other project provided)
Now you can see the projects and code. You'll find that the code comments walk you through the options and APIs you'll need to use to make the most of what's built-into ECF.
4. Build the new projects
5. Copy the .dlls for the aforementioned projects (PaymentProviderConfiguration.dll and PaymentProviderExample.dll) into the B2CSampleSite bin folder.
6. Create a new folder in the Apps/Orders/Payments/Plugins folder of the shared location referenced in the IIS configuration of the site. Call the folder CustomPayment.
7. Copy the ConfigurePayment.ascx file from the PaymentProviderConfiguration project into this new folder.
8. Open Commerce Manager
9. Goto Administration/Order System/Payments/English.
10. Select New.
11. Enter fields :
- Whatever Name you desire
- The system keyword has to be CustomPayment to correspond to the previously-made folder.
- Class name needs to be the new payment gateway that's been incorporated : PaymentProviderExample.CustomPaymentProvider.
- Is Active is true.
12. Press OK.
13. From the payment methods list, reselect the new method you just set up.
14. Goto the parameters tab. Notice that there are two parameters loaded/saved here.
15. Return to the public site.
16. Checkout - notice on the payment method page that your new payment method shows up.
Here are the download files : PaymentProviderExample.zip
In the ECF B2CSample site, you'll notice that there are unique fields that need to be filled in for each payment method. In most cases, you'll want the user to provide information regarding the payment method, like an invoice number, gift card number, or credit card fields. The B2CSample site uses a particular pattern you may find useful to more easily add the payment method display in your site. Here are the steps to create a new payment processing UI for a payment method:
1. First determine which payment method you are creating a payment control for.
2. Create a new folder under Templates/Everything/BusinessControls/CheckoutControls/plugins/payment. Give it the same name as the system keyword for the payment method.
Mediachase.Commerce.Orders (IShippingGateway, Payment types)
Mediachase.Commerce.Plugins.Payment (Payment Gateway classes)