How to write a Payment Plugin

Owned by Former user (Deleted)
Last updated: Jun 06, 2018 by Marcus Gesing

Create a payment provider class

The payment provider is the most important part of a payment plugin and implements the main functions of a payment method. A plugin can contain any number of payment providers and thus any number of payment methods. The provider should inherit from class PaymentMethodBase and optionally from IConfigurable. Decorate the provider with required attributes:

  • SystemName: The system name of the provider.
  • FriendlyName: The friendly name of the provider.
  • DisplayOrder: The display order in payment method lists.
  • DependentWidgets: Optional. System name of a widget that should be activated\deactivated when the payment method is activated\deactivated.

Example:

[SystemName("Payments.PayoneCreditCard")]
[FriendlyName("Payone credit card")]
[DisplayOrder(10)]
[DependentWidgets("Widgets.Payone")]
public class CreditCardProvider : PaymentMethodBase

Develop the core implementation of your payment method by overriding the properties and methods of PaymentMethodBase. 

Properties of PaymentMethodBase

  • RequiresInteraction: Gets a value indicating whether the payment method requires user input before proceeding in checkout (e.g. credit card payment).
  • PaymentMethodType: Choose a type that best suits your payment method. See values below.
  • IsActive: Gets a value whether the payment method is active (whether it is displayed in the checkout payment list). Typically used for license checks.
  • SupportCapture: Gets a value indicating whether payment capturing is supported. If true, then you must overwrite the method Capture.
  • SupportPartiallyRefund: Gets a value indicating whether partially refunds are supported. If true, then you must overwrite the method Refund.
  • SupportRefund: Gets a value indicating whether refunds are supported. If true, then you must overwrite the method Refund.
  • SupportVoid: Gets a value indicating whether the provider supports payment cancellation. If true, then you must overwrite the method Void.

Values of PaymentMethodType

  • Unknown: Type is unknown.
  • Standard: All payment data is entered in the store, e.g. credit card payment, where all data is entered in the checkout.
  • Redirection: The customer will be redirected to a page of the payment provider after the order has been placed for the purpose of payment.
  • Button: The payment process is initiated via a button in the checkout.
  • StandardAndButton: The payment process is initiated via a button in the checkout and all payment data is entered in the store.
  • StandardAndRedirection: Rare special case. Payment information is entered in checkout and customer is redirected to complete payment (e.g. 3D Secure) after the order has been placed.

Methods of PaymentMethodBase

  • GetControllerType: The type of the payment controller (see below). E.g. typeof(PayoneCreditCardController)
  • GetAdditionalHandlingFee: Optionally gets additional fees for handling the payment method.
  • CanRePostProcessPayment: Only relevant for the types Redirection and StandardAndRedirection. Gets a value indicating whether the payment process can be restarted by the customer by pressing a button on order detail page.
  • GetPaymentInfoRoute: Gets route values to a partial view that provides payment information displayed in checkout payment list.
  • PreProcessPayment: Called while placing an order but before the order object has been created and stored into the database. Typically used for preauthorization when the payment gateway reports a failure that leads to order cancellation.
  • ProcessPayment: Same as PreProcessPayment but called a little later, immediately before the order object is created. Order placement can still be aborted here by returning an error. The returned object ProcessPaymentResult contains a property NewPaymentStatus that should be set to the current payment status, e.g. PaymentStatus.Paid if the payment can be considered completed at this time. See values below.
  • PostProcessPayment: Called after an order has been placed. Typically used when data of the order object is required like the order identifier. If the payment method requires redirection (type Redirection or StandardAndRedirection), then this method must provide the URL to which you want to redirect.

Values of PaymentStatus

  • Pending: The initial payment status if no further status information is available yet.
  • Authorized: The payment has been authorized (but not executed) by the payment gateway.
  • Paid: The payment has been executed against the payment gateway. It does not necessarily mean that the paid amount has been credited to the merchant's account.
  • PartiallyRefunded: The paid amount has been partially refunded.
  • Refunded: The paid amount has been fully refunded.
  • Voided: The payment has been cancelled.

Create a payment controller

Create a controller class and inherit from PaymentControllerBase. Add an action method PaymentInfo that returns a partial view with information about your payment method displayed in checkout payment list. Optional (if required): Add endpoints for the payment gateway of your payment method. For instance IPN (instant payment notification) should be handled here.

Methods of PaymentControllerBase

  • ValidatePaymentForm: Used to validate the form data entered by the customer in checkout, for example a credit card number.
  • GetPaymentInfo: Deprecated method to temporary store data entered by the customer in checkout. Better use HttpContextBase.GetCheckoutState().CustomProperties if you need session based data storing during checkout.
  • GetPaymentSummary: Optional. Returns a string as short summary of the data entered by the customer in checkout.
  • PaymentInfo: Action method that returns a partial view with information about your payment method displayed in checkout payment list.

Tips & Tricks

Add order notes for each data exchange you have with the payment gateway. This allows the merchant to track which and when data has been exchanged with the payment provider.

Log all errors (in detail) that occurred while exchange data with the payment gateway. This information makes it easier for the payment provider's support to determine the cause of a payment problem.

Optionally store and use payment indentifiers on order level:

  • AuthorizationTransactionId: The payment provider's identifier of the authorization object.
  • AuthorizationTransactionCode: An additional field in the context of authorization, e.g. an authorization result code of the payment provider.
  • AuthorizationTransactionResult: An additional field in the context of authorization, e.g. a short status message like Open.
  • CaptureTransactionId: The payment provider's identifier of the capture object.
  • CaptureTransactionResult: An additional field in the context of capturing, e.g. a short status message like Completed. 

These identifiers are displayed on the order page in the backend, but they are not further processed or used in any other way by SmartStore.NET.

Add order notes for each IPN (instant payment notification) you receive from the payment gateway. Set HasNewPaymentNotification of the order entity to true if you receive a new IPN. A small info badge appears in the order list indicating that a new IPN has been received for this order.

If required, use the entity GenericAttribute (with KeyGroup set to Order) to store any extra payment data for an order. Typically the payment data is JSON serialized in this case.