# Wednesday, May 19, 2010

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. This information is based onuCommerce 1.0.3.x and 1.0.3.2.

Create Visual Studio Project

Create a new Visual Studio solution and choose Class Library for your project type.

 Project structure - File Explorer

 

Add References to Your Project

uCommerce.dll

uCommerce.Infrastructure.dll

Subsonic.Core.dll

VS add reference select UC assemblies

Import Namespaces

Import the UCommerce.Transactions.Payment and UCommerce.Entities namespaces in you class file

Import namespaces

Implement interface IPaymentMethodService on your class

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.

Implement interface 

Implement interface 2

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

With uCommerce 1.0.3.2 the option for deferred payment requests was introduced meaning that 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 PaymentMethodService should implement the interface IPaymentFactory (new for version 1.0.3.2), 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 Your Assembly to Your Umbraco Site

Copy MyUCommerceApp.Library.dll to the /bin folder of your Umbraco 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" />

image 

Configure Payment Method to Use Your Service

Configure Payment Method to use your new service in uCommerce Backoffice.

Configure Payment Method to use PaymentMethodService - 2 

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())"/>

The uCommerce Store executes CreatePayment in the macro called UpdatePayment[XSLT].

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);
}
Comments are closed.