IPaymentProviderReport interface

Litium.Foundation.Modules.ECommerce.Plugins.Payments.IPaymentProviderReport interface has a single method, which is called by the Litium Studio API, when the payment provider sends status updates of existing orders to Litium Studio.

Not every payment provider has this capability, and the technical name used to call these status updates may vary based on the provider.

To receive the status updates, following two need to be done:

1. The payment provider plugin should implement the IPaymentProviderReport interface.
2. The payment provider should be configured (usually through its admin site) with the correct url to reach Litium Studio.

Implementing IPaymentProviderReport interface

The method to implement has the following signature:

void OnProviderReportCallback(HttpRequestBase request, HttpResponseBase response, SecurityToken token)

Parameters

1. request: HTTP request received to Litium Studio. This object should contain the necessary query string (or HTTP Post data) to identify the order and the payment info object. Also, it should contain the status of the payment.
2. response: HTTP response that will be sent back to the payment provider. The exact response to send will be specified by the payment provider.
3. token: Admin token of ECommerce module

Implement this interface in the same class as the IPaymentProvider interface is implemented.

Also, you need to reference the assembly System.Web.Absractions so that System.Web.HttpRequestBase entity is available.

Thread safety

The implementation should be thread safe, because the payment provider may send several calls at the same time for the same order, or it can be the case that Litium Studio is Synchronizing the payment status at the same time this call is received. (see under Synchronizing payment status article).

To make the method thread safe, use the Litium.Utilities.LogicalSyncLock and use the payment info id as the sync root. Do not use the normal lock statement as it will cause only one payment to be processed at a time hugely impacting the performance.

PaymentInfo object is not set by the api

When this method is called, the API has not initialized the plugin with the PaymentInfo obect. Therefore, the PaymentInfo object is null at the begining of this method., and need to be set via the SetPaymentInfo method call. (The reason why API is not setting this is, that api is not aware of how to find the order and the payment info relating to this call received, and its only the plugin which is aware of how to find the correct order.)

Sample code

Following is a sample implementation: You need to additionally reference Litium.Utilities and System.Web.Abstractions asssemblies.

You may need following using statements.

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Net.Sockets;
using System.Text;
using Litium.Owin.InversionOfControl;
using Litium.Foundation;
using Litium.Foundation.Log;
using Litium.Foundation.Modules.ECommerce;
using Litium.Foundation.Modules.ECommerce.GUI;
using Litium.Foundation.Modules.ECommerce.Orders;
using Litium.Foundation.Modules.ECommerce.Payments;
using Litium.Foundation.Modules.ECommerce.Plugins.Payments;
using Litium.Foundation.Security;
using Litium.Studio.AddOns.Samples.TestPaymentsProvider.Configuration;
using Litium.Utilities;

        /// <summary>
        /// Called when payment provider sneds status updates to Litium Studio.
        /// </summary>
        /// <param name="request">The request.</param>
        /// <param name="response">The response.</param>
        /// <param name="token">The token.</param>
        public void OnProviderReportCallback(System.Web.HttpRequestBase request, System.Web.HttpResponseBase response, SecurityToken token)
        {
            //obtain the order id and the paymentinfo id from the request.
            //query string keys may differ from payment provider to provider.
            var orderId = request["orderId"];
            var paymentInfoId = request["paymentInfoId"];
            var status = request["status"];

            //gaurd against raise condition of same call getting called twiced for the same payment.
            //do not use ordinary "locks" as this will cause only one payment to be processed at a time.
            //instead use the Litium.Utilities.LogicalSyncLock
            string syncRoot = paymentInfoId;
            try
            {
                LogicalSyncLock.Enter(syncRoot);

                //find the payment info.
                PaymentInfo paymentInfo = null;
                Order order = ModuleECommerce.Instance.Orders.GetOrder(orderId, token);
                if (order != null)
                {
                    foreach (var item in order.PaymentInfo)
                    {
                        if (item.ReferenceID == paymentInfoId)
                        {
                            paymentInfo = item;
                            break;
                        }
                    }
                }               
                if (paymentInfo != null)
                {
                    //initialize the plugin with current payment info.
                    SetPaymentInfo(paymentInfo);
                    //TODO: change the paymentInfo payment status based on the status received from the payment provider

                    //response written back depends on provider.
                    response.Write("OK");
                }
                else
                {
                    //If the payment info is not found, there is a misconfiguration at the payment providers side.
                    //they are sending the status to the wrong Litium Studio installation.
                    var msg = string.Format("Corresponding payment not found for HTTP report callback {0}", request.Url.ToString());
                    Solution.Instance.Log.CreateLogEntry(" Http report callback failure", msg, LogLevels.ERROR);
                    
                    //response written back depends on provider.
                    response.Write("FAIL");
                }
            }          
            catch (Exception e)
            {
                //TODO: handle any exceptions and log error message to foundation log.
                //response written back depends on provider.
                response.Write("FAIL");
            }
            finally
            {
                LogicalSyncLock.Exit(syncRoot);
            }
        }

when the status is received from the payment provider, that status might not exactly match the payment info payment status used by Litium Studio. This matching has to be done in the plugin and correct status set. Best way to do this is explained in the Synchronizing payment status article.

Configuring payment provider to call Litium Studio

The payment provider should be configured to call the Litium Studio when a status update is available. The url that should be provided to the payment provider has the following form:

http://yourServerDomain/PaymentProviderResult.axd/Report/PaymentProviderPluginName

For example, in case of payment provider "Plugin" attribute is set as below:

   /// <summary>
    /// A sample payment provider for testing checkout flows.
    /// </summary>
    [Plugin(TestPaymentsProvider.ProviderName)]
    public class TestPaymentsProvider:PaymentProviderBase, IPaymentProvider, IPaymentProviderReport
    {
        /// <summary>
        /// The payment providers name.
        /// </summary>
        public const string ProviderName = "TestPaymentsProvider";

     }

Then the call report callback url is:

http://yourServerDomain/PaymentProviderResult.axd/Report/TestPaymentsProvider

Note the name "TestPaymentsProvider" at the end of the above url, which is the same name used to identify the plugin.