Integrating Ucommerce with a Payment Provider
You will learn how to create a Payment Method Service, which integrates Ucommerce with an online payment processer such as Sage, DIBS, PayPal, Cyber Source, or another processor used during checkout.
Create Visual Studio Project
Create a new Visual Studio solution and choose Class Library for your project type.
Add a reference to your project
- Ucommerce.dll
- Ucommerce.Infrastructure.dll
Import namespaces
Import the UCommerce.Transactions.Payments and UCommerce.EntitiesV2 namespaces in your class file.
Implement Interface IPaymentMethodService
The IPaymentMethodService interface gives you full control over the behavior of the service. Alternatively you can inherit from AbstractPaymentService, which gives a default implementation for ProcessPaymentRequest, which will give you a properly initialized Payment.
using UCommerce.Transactions.Payments
namespace MyUcommerceApp.Library
{
public class MyPaymentService : IPaymentMethodService
{
public Payment RequestPayment(PaymentRequest request);
{
}
public Payment ProcessPaymentRequest(PaymentRequest request)
{
}
public Payment AcquirePayment(Payment paymentToAcquire)
{
}
public Payment CancelPayment(Payment paymentToCancel)
{
}
public Money CalculatePaymentFee(PaymentRequest request)
{
}
public string Name { get; set; }
}
}
Implement Name Property
The name property is used to uniquely identify your Payment Method Service. It is read from configuration and set on your service at runtime.
public class MyPaymentService : IPaymentMethodService
{
public string Name { get; set; }
}
Implement RequestPayment(PaymentRequest)
RequestPayment can be used in one of two ways: 1) Either to redirect the customer to the remote server handling payment information there, e.g. credit card information, or 2) to simply send payment information received on your server directly to the provider.
1)
public Payment RequestPayment(PaymentRequest request)
{
// Package up information for the backend service,
// in the form of a http request
// Redirect customer to backend service with
// the needed information
// Payment would be set pending authorization status (the status will have to be added to the Ucommerce_PaymentStatus table)
}
2)
public Payment RequestPayment(PaymentRequest request)
{
// Processing is happening synchronously so we just
// call the backend service with ProcessPaymentRequest
return ProcessPaymentRequest(request);
}
Implement ProcessPaymentRequest(PaymentRequest)
ProcessPaymentRequest is used to handle any processing before or callbacks from the remote server in the case of a payment processing being handled exclusively by a remote party.
1) In the case of a callback scenario you use ProcessPaymentRequest to handle the callback and do any needed processing like updating order status. To receive the callback an endpoint needs to be exposed to the remote party such an http handler or a module. The handler or module will call ProcessPaymentRequest to complete the payment.
public Payment ProcessPaymentRequest(PaymentRequest request)
{
// Update payment according to received status from remote
// party, e.g. Accepted, Declined
// Grab any transaction ids and put them on the payment before
// returning the Payment
}
2) For a synchronous scenario ProcessPaymentRequest would be used to perform the query to the backing system and create a new Payment according to the result received.
public Payment RequestPayment(PaymentRequest request)
{
// Package up information for the backend service,
// in the form of a http request
// Redirect customer to backend service with
// the needed information
// Payment would be set pending authorization status
}
Implement AcquirePayment(Payment)
For legal reason you sually can’t withdraw money from the customer until you actually ship their order. AcquirePayment is ment for this very scenario where you first authorize the payment and later withdraw from their account.
AcquirePayment(Payment) is used for capturing the payment from the customer.
public Payment ProcessPaymentRequest(PaymentRequest request)
{
// Send request to remote party
// Update payment according to received status from remote
// party, e.g. Accepted, Declined
// Grab any transaction ids and put them on the payment before
// returning the Payment
}
Implement CancelPayment(Payment)
If you wish to cancel af payment with your payment method service you need to implement CancelPayment, and have it reach out the remote payment processor. Typical scenarios for cancelling a payment includes a customer return, cancelled order and typically requires you to handle two scenarios: Payment authorized but not capture and payment authorized and captured.
public Payment CancelPayment(Payment payment)
{
// Update payment according to received status from remote
// party, e.g. Cancelled
// Grab any transaction ids and put them on the payment before
// returning the Payment
}
Implement CalculatePaymentFee(PaymentRequest)
If applicable, used for calculating the fee associated with the payment method.
public virtual Money CalculatePaymentFee(PaymentRequest request)
{
var order = request.PurchaseOrder;
var paymentMethod = request.PaymentMethod;
var fee = paymentMethod.GetFeeForCurrency(order.BillingCurrency);
if (!order.SubTotal.HasValue)
return new Money(0,
new CultureInfo(Globalization.CultureCode), order.BillingCurrency);
return new Money(order.SubTotal.Value
* (paymentMethod.FeePercent / 100)
+ fee.Fee,
new CultureInfo(Globalization.CultureCode), order.BillingCurrency);
}
Optionally Implement IPaymentFactory Interface on Your Provider
You can create a payment placeholder for the choices made by a user and then later perform the actual payment request to the backend service.
If you need this functionality your service should implement the interface IPaymentFactory, which will be used for creating the new Payment.
/// <summary>
/// Creates a new payment fully initialized
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
public Payment CreatePayment(PaymentRequest request)
{
PurchaseOrder order = request.PurchaseOrder;
var payment = new Payment {
TransactionId = Guid.NewGuid().ToString(),
OrderId = order.OrderId,
PaymentMethodName = GetPaymentName(request.PaymentMethod),
Created = DateTime.Now,
PaymentMethodId = request.PaymentMethod.PaymentMethodId,
Fee = CalculatePaymentFee(request).Value,
FeePercentage = request.PaymentMethod.FeePercent,
PaymentStatusId = 1, // Status new
Amount = request.Amount.Value
};
return payment;
}
Copy Assembly to Your Site
Copy MyUCommerceApp.Library.dll to the /bin folder of your site.
Add Your Payment Method Service to web.config
Configure your new Payment Method Service in web.config of your Umbraco site.
In the
<paymentMethodServices>
element of you web.config add the following xml:
<add name="MyPaymentMethodService" type="MyUCommerceApp.Library.MyPaymentMethodService, MyUCommerceApp.Library" />
<commerce>
<runtimeConfiguration
componentConfigurationFile="C:\inetpub\wwwroot\umbraco\ucommerce\configuration\Components.config" />
<catalogConfiguration
defaultCultureCode="en-US" />
<ordersConfiguration>
<shippingMethodServices>
<add name="SinglePriceService"
type="UCommerce.Transactions.Shipping.SinglePriceShippingMethodService, UCommerce" />
</shippingMethodServices>
<paymentMethodServices>
<add name="(default)"
type="UCommerce.Transactions.Payment.DefaultPaymentMethodService, UCommerce" />
<add name="MyPaymentMethodService"
type="MyUCommerceApp.Library.MyPaymentMethodService, MyUCommerceApp.Library" />
</paymentMethodServices>
</ordersConfiguration>
</commerce>
Configure Payment Method to Use Your Service
Configure Payment Method to use your new service in Ucommerce Backoffice.
Execute Your Payment Method Service from Commerce XSLT Library
You have two options when you need to carry out your payment request: Either create and request a payment in one go by or do a two step request whereby you create a payment, but defer the actual request of the payment to backend service to a later time.
Please note that the two-step request is only available with Ucommerce 1.0.3.2 or newer.
Typically the two step approach is used when you’re dealing with a redirect scenario in which part of the payment authorization happens on a remote server.
For a single step request, you'll use this XSLT extension:
<xsl:variable name="result" select="CommerceLibrary:CreatePayment($paymentMethodId, -1, true(), true())"></xsl:variable>
Or the version with no amount argument, which will default to the SubTotal of the PurchaseOrder, i.e. use this if you only accept one payment per purchase order.
If you need the two step version you’ll use a couple of extensions. First the one which creates a payment for you and second an extension, which performs the request. Please note that your PaymentMethodService must implemention IPaymentFactory for this to work.
// -1 is a convenience which will tell Ucommerce to grab the total of the order for the payment
// The first bool parameter indicates whether to perform the payment request
// The second bool parameter will overwrite existing payments if set to true (a way to avoid duplicates)
<xsl:variable name="result" select="CommerceLibrary:CreatePayment($paymentMethodId, -1, false(), true())"/>
To perform the payment request you’ll execute:
// Perform request payment for all payments associated with the basket
<xsl:variable name="paymentResult" select="CommerceLibrary:RequestPayments()"/>
or
// Perform request payment for a single payment
<xsl:variable name="paymentResult" select="CommerceLibrary:RequestPayment(paymentId)"/>
Execute Your Payment Method Service from .NET
To execute your Payment Service directly from .NET code you use the following snippet:
public void ExecutePaymentMethodService(PaymentMethod paymentMethod,
PurchaseOrder purchaseOrder, decimal amount)
{
var cultureInfo = new CultureInfo(Globalization.CultureCode);
// Create a new payment request to
var paymentRequest = new PaymentRequest(
purchaseOrder,
paymentMethod,
new Money(
amount,
cultureInfo,
purchaseOrder.BillingCurrency));
Payment payment = paymentMethod
.GetPaymentMethodService()
.RequestPayment(paymentRequest);
}