Connecting to payment gateways

When building the checkout process on your e-commerce site, you may want to enable your customers to pay directly via a payment gateway (e.g. PayPal or credit card).

This page demonstrates how to work with API from the CMS.Ecommerce assembly (installed into your project as part of the Kentico.Xperience.Libraries integration package) that deals with payment of orders. However, the specific implementation can differ for each service, and we recommend that you work closely with documentation of the implemented payment gateway provider.

You need to implement payment gateways for the payment methods in the live site application itself and add the related payment methods to Xperience via the administration interface.

Configuring payment methods in Xperience

Set up all payment methods for which you want to implement a payment gateway as manual payment methods.

See Configuring payment methods to learn more about manual payment methods.

When configuring the payment method, leave the Payment gateway URL and Payment gateways provider class fields blank. The live site application decides which payment gateway to use based on the method’s code name.

Note: Payment gateways that you implement in your live site application cannot be used from the administration interface of the Xperience application (for example when manually creating or editing orders).

Developing payment gateways

In the controller action of the last checkout process step (usually the order review step), redirect the customer to a controller that takes care of the specific payment gateway.

If you provide multiple payment methods and you need to distinguish their payment gateways, check the cart’s payment method code name. For example:




            if (shoppingCart.PaymentOption.PaymentOptionName.Equals("PaymentMethodCodeName"))
            {
                return RedirectToAction("ActionForPayment", "MyPaymentGateway");
            }

Most payment service providers require a specific way of interfacing with their payment service. You need to implement the connection in a way that adheres to the provider’s documentation and specification.

The payment gateway then receives a response from the service. Create a new PaymentResultInfo object with information from the response. Use the UpdateOrderStatus method of the OrderInfo object representing the order to save the payment result to the database. For example:




            if (response != null)
            {
                // Gets the order based on the invoice number from the response
                OrderInfo order = orderInfo.Get(response.InvoiceNo);
                if (order?.OrderSiteID != siteService.CurrentSite.SiteID)
                {
                    order = null;
                }

                // Checks whether the paid amount of money matches the order price
                // and whether the payment was approved
                if (order != null && response.Amount == order.OrderTotalPrice && response.Approved)
                {
                    // Creates a payment result object that will be viewable in Xperience
                    PaymentResultInfo result = new PaymentResultInfo
                    {
                        PaymentDate = DateTime.Now,
                        PaymentDescription = response.Message,
                        PaymentIsCompleted = response.Completed,
                        PaymentTransactionID = response.TransactionID,
                        PaymentStatusValue = response.ResponseCode,
                        PaymentMethodName = "PaymentName"
                    };

                    // Saves the payment result to the database
                    order.UpdateOrderStatus(result);
                }
            }

The system sets the order status as configured in the payment method.