OnProviderCallback method
When the control is transferred to the payment providers site, end customer enters his credit card information and confirms the purchase. Then the payment provider will return the control back to Litium Studio by redirecting to the responseUrl (or Cancel url if user cancelled). These urls are given to the payment provider in a previous initialization call, or when the HTTP post to the provider site is done.
This article explains how to handle this payment provider callback.
IPaymentProvider.OnProviderCallback is not always called
The IPaymentProvider.OnProviderCallback method is called only if the control is previously transfered to the payment provider site. Certain payment providers such as Klarna or HandelsbankenFinans when in webservice mode do not transfer control ourside Litium Studio but rely only on web service calls. In such cases this method is not called.
IPaymentProvider.OnProviderCallback method parameters
- queryString: Contains the order reference and paymentinfo references to identify the order and the payment, its status and security hashes. Note that the original query string is being decoded by the Litium Studio API and the order and the PaymentInfo object is already initialized when this method is called. Therefore, the PaymentInfo object that is in the PaymentProviderBase class is already initialized.
- isSuccess: is set to true if the provider redirected to the response url and set to false if the provider redirected to the cancel url. Important: isSuccess=true does not mean that the transaction status is a success. The transaction status is a payment provider dependent parameter which is always communicated with the queryString. Therefore, the transaction can either be a success or a failure even if the isSuccess parameter is true. However, if the parameter is false, the transaction has definitely being cancelled by the user.
- token: This will always be the admin token with highest level of permissions, because the method is being called by the API. API verifies the hashes from original call from payment provider to guarantee that it is not manupilated.
Implementation
The basic implementation is to check the current payment status. Since this call is comming from the payment provider, Litium Studio payment status need to be updated based on the actual transaction status.
Following example sets the payment status and shows how to set the return result.
/// <summary>
/// Called from when payment provider calls back to Litium Studio as part of the checkout flow.
/// </summary>
/// <param name="queryString">The query string.</param>
/// <param name="isSuccess">if set to <c>true</c> [is success].</param>
/// <param name="token">The token.</param>
/// <returns></returns>
/// <exception cref="System.NotImplementedException"></exception>
public ProviderCallbackResult OnProviderCallback(System.Collections.Specialized.NameValueCollection queryString, bool isSuccess, Foundation.Security.SecurityToken token)
{
//initialize the return value to be a failure, and we set this to a success if transaction status is a success.
var result = new ProviderCallbackResult(false, string.Empty);
//information received in query string.
//these information and its keys will be different from provider to provider. Following is a sample.
var transactionRef = queryString["ref"];
var transactionStatus = queryString["status"];
PaymentInfo.SetTransactionReference(transactionRef, token);
if (isSuccess)
{
//provider redirected to response url. We need to check transaction status in the query string.
if (transactionStatus == "Success")
{
//change result to notify a success.
result.Success = true;
if (PaymentInfo.PaymentStatus == PaymentStatus.ExecuteCharge)
{
PaymentInfo.SetPaymentStatus((short)PaymentStatus.Paid, token);
}
else if (PaymentInfo.PaymentStatus == PaymentStatus.ExecuteReserve)
{
PaymentInfo.SetPaymentStatus((short)PaymentStatus.Reserved, token);
}
}
else if (transactionStatus == "Pending")
{
PaymentInfo.SetPaymentStatus((short)PaymentStatus.Pending, token);
//change result to notify a success.
result.Success = true;
//but set the message to notify its still pending.
//Note: display of this message is entirely dependent on how the Checkout flow page template is done.
result.ErrorMessage = "payment is still pending";
}
else
{
if (PaymentInfo.PaymentStatus == PaymentStatus.ExecuteCharge)
{
PaymentInfo.SetPaymentStatus((short)PaymentStatus.ChargeFailed, token);
}
else if (PaymentInfo.PaymentStatus == PaymentStatus.ExecuteReserve)
{
PaymentInfo.SetPaymentStatus((short)PaymentStatus.ReserveFailed, token);
}
//note that this is a failure, change the return result message.
//Note: display of this message is entirely dependent on how the Checkout flow page template is done.
result.ErrorMessage = "payment failed";
}
}
else
{
//provider redirected to the cancel url.
PaymentInfo.SetPaymentStatus((short)PaymentStatus.Cancelled, token);
//record result as a user friendly message in the paymentInfo external message.
//this message is visible when viewing paymentinfo in the LitiumStudio backoffice.
PaymentInfo.AppendExternalMessage(DateTime.Now.ToString(CultureInfo.InvariantCulture) + " user cancelled", token);
//when the return result success is set to false, its message will be displayed to the end user.
//Note: display of this message is entirely dependent on how the Checkout flow page template is done.
result.ErrorMessage = "user cancelled"; //in practice, provide language transactions.
}
return result;
}