Handelsbanken Ecster

The invoices can be dispatched to the customer by the merchant or by Handelsbanken Ecster. Usually the customer gets a grace period to pay the invoice, but the merchant gets the money (less any fees and commissions) immediately when a transaction is accepted by Handelsbanken Ecster. Collection of money from the end customer and any associated risks are usually born by Handelsbanken Ecster.

The main advantage of this method is the ability to promote sales through part payment deals, where end customer is paying each month, but the merchant receives the money upfront.

Features

• Payments through invoice (faktura).
• Payment through Handelsbanken Ecster account and part payments (delbetalning).
• Multi market support: multiple Handelsbanken Ecster accounts in same Litium Studio installation.
• More information: www.handelsbanken.se

Configure Handelsbanken Ecster

Before you begin, contact Handelsbanken at www.handelsbanken.se/ehandel  and obtain the test account information.

You will receive following information from Handelsbanken:

• contractNumber: Contract number to be used in config file.
• Api user name: API user name to be used in config file
• Api user password: API user password to be used in config file
• mac : Mac key to be used in the config file.
• Handelsbanken backoffice login credentials to https://test.saljfinans.handelsbanken.se/butiksadmin/

To configure from Handelsbanken side

You should give following information to them:

• Your organization number
• IP address and domain name of your site.
• OSN report url: http://<your domain name>/PaymentProviderResult.axd/Report/HandelsbankenFinans    (please see below under Callback reports heading)

Important pre-requisites

• Handelsbanken always work in the payment style "Reserve" mode. You need to edit your checkout page and in settings tab, put it to reserve mode.
• Handelsbanken will not allow same order containing different VAT percentages. If a single order has order rows with more than one VAT band then those orders will be rejected.

Installing Handelsbanken Ecster Provider

Download the latest version from add-ons section and follow the installation instructions contained in the package.

Configuring Handelsbanken Ecster Provider

Use the Litium.Studio.AddOns.HandelsbankenFinans.dll.config file in the wwwroot\bin directory (created from Litium.Studio.AddOns.HandelsbankenFinans.dll.config.tmpl file) after installation. All instructions are at the top of this file as well.

Following are the configuration options available.

• apiVersion: HandelsbankenFinans API version. Should not be changed.
• checkoutServerUrl: Url to the HandelsbankenFinans checkout server, where checkout page is redirected to, when user clicks order confirmation button.
• webserviceHostUrl: host Url to the Handelsbanken webservice.
• paymentAccount: the contract (account) merchant has with HandelsbankenFinans. Can have multiple contracts, and each contract need a seperate paymentAccount section.
• paymentAccIdentifier: Identifier to select the account. Must be unique and is mandatory. The AdditionalPaymentInfo of the payment should contain this value in additionalPaymentInfoKeyForPaymentAccId key, in order to select the correct account for each payment. see example at the end of this file. payment methods from this account will have this prefix appended at the begining, when viewing in back-office and API methods.
• apiUser: User name used in webservice calls.
• apiPassword: Password used in webservice calls.
• contractNumber: contractNumber given from HandelsbankenFinans to your account with HandelsbankenFinans.
• useHandelsbankenFinansCheckout: set to true, if checkout pages from handelsbanken should be used (user is redirected to Handelsbanken site). If set to false, the webservice api will be used and user is not redirected to Handelsbanken site.
• mac: MAC provided for regular webservice calls to handelsbanken., if empty, it is treated as optional and MAC verification is not done.
• osnMAC: OSN-MAC secret word provided by HandelsbankenFinans OSN calls.
• useTestMode: if set to true, an invoice is created in test mode. Set to false when in production.
• isInvoiceEnabled: true if invoice payment method is enabled.
• isPayUsingAccountEnabled: true if paying using handelsbanken account is enabled. Partial payments can only be made through this method.
• accountApplicationAmount: the amount specified when applying for a new account, if checkoutflow has not specified any amount. to specify amount through checkoutflow project should implement IHandelsbankenFinansCheckoutFlowInfo in CheckoutFlowInfo by extending default CheckoutFlowInfo, and set its values.
• accountApplicationMinAmount: Do not change this value without contacting Handelsbanken first.
  the minimum amount specified when applying for a new account, if checkoutflow has not specified any amount. to specify amount through checkoutflow project should implement IHandelsbankenFinansCheckoutFlowInfo in CheckoutFlowInfo by extending default CheckoutFlowInfo,and set its values.
• accountApplicationMaxAmount:  Do not change this value without contacting Handelsbanken first.The minimum amount specified when applying for a new account
• minYearlySalary: yearly salary when applying for a new account, if checkout flow has not specified any amount. value should be between 0-999. To specify amount through checkoutflow project should implement IHandelsbankenFinansCheckoutFlowInfo in CheckoutFlowInfo by extending default CheckoutFlowInfo, and set its values.
• minimumFixedMonthlyPayment: minimum monthly amount acceptable to merchant when customer is paying a fixed amount each month.
• calculateCampaignsOffline: calculate the Handelsbanken campaigns offline. This should be set to false, unless adviced specifically to turn it on by Handelsbanken or Litium.

Translatable website strings

The error messages from Handelsbanken can be translated in the website as website strings. Following are the website string keys and a example default value you can use. If the website string is not present status message from Handelsbanken will be displayed.

HandelsbankenFinansStatusUnknown: "Unknown status"

HandelsbankenFinansStatusReadyForDelivery: "Shipment ready for delivery"

HandelsbankenFinansStatusDenied: "Account application or credit denied for the payment."

HandelsbankenFinansStatusTechnicalError: "A technical error has occured. Please use a different payment method"

HandelsbankenFinansStatusReview: "The payment is in 'Review' status. Items bought will be shipped when the payment is approved".

HandelsbankenFinansApplicationId: "Account application ID"

HandelsbankenFinansCaseNumber: "Case no."

Testing

Note that following informaiton is also present at the top of Litium.Studio.AddOns.HandelsbankenFinans.dll.config file.

•  The test information can be found at https://test.saljfinans.handelsbanken.se/testportal/sv/start.html
   
•   https://test.saljfinans.handelsbanken.se/orderpanel/ contains a way of approving and signing test account requests. Put the organization number and the contract number in input boxes below and click the Hämta button. Then you can sign the contracts, by selecting the order and clicking the Signera avtal button, which will move account orders with unsigned contracts in Pending state to approval (levarans klar in Handelsbanken). An OSN report will notify studio automatically of the state change, and Litium Studio will change payment status accordingly.
   
•   Created test orders can be viewed from https://test.saljfinans.handelsbanken.se/butiksadmin ,use login name and password provided by handelsbanken.
   
•   Detailed test instructions on testing payments by "Account" that goes to "Pending" state can be found here >>.

Call back reports from Handelsbanken (OSN Reports)

Some payment might go into "Pending" state (Most common is when account payments are made, if the customer does not sign the contract online,). In this case, after verifification Handelsbanken will change the status in thier side, and notify Litium Studio of the payment status through a server callback functionality.

Handelsbanken calls them as OSN reports in their terminology. 
  To be able to receive correct OSN reports, Handelsbanken should configure the account with the following url:
  http://<merchant domain name>/PaymentProviderResult.axd/Report/HandelsbankenFinans

Using Handelsbanken Ecster webcontrols

Handelsbanken Ecster provider comes with webcontrols that will ease up development when showing part payment options to the end customers. All web controls does not require any specific Code Behind logic to be written, but should be placed inside a control which implements IOrderCarrierIntroducer such as Ecom:ShoppingCartPanel webcontrol.

To use this example, your web.config file should contain the following entry:

<pages>
<controls>
<add tagPrefix="shb" namespace="Litium.Studio.AddOns.HandelsbankenFinans.WebControls" assembly="Litium.Studio.AddOns.HandelsbankenFinans"/>
</controls>
</pages>

Webcontrols that show part payment options (Handelsbanken campaigns)

Following example shows all the webcontrols that will display all partpayment options. Create a Litium Studio page template and have the following inside it to display all partpayment options.

<%@ Page Language="C#" AutoEventWireup="false" Inherits="App_Code.Site.CMS.Templates.BaseTemplate" %>

<asp:Content ContentPlaceHolderID="Content" runat="server">
    <Ecom:ShoppingCartPanel ID="m_shoppingCartPanel" runat="server">
         <table class="ordertotals orderdata common">
         <tr>
         
         <td><b>Part payment option</b></td>
         <td><b>Admin Fee</b></td>
         <td><b>Campaign fee</b></td>
         <td><b>Max amount</b></td>
         <td><b>Min amount</b></td>
         <td><b>Min limit</b></td>
         <td><b>Description</b></td>
         <td><b>Other</b></td>
         
         </tr>
         
         <Shb:PartPaymentOptionRepeater ID="PartPaymentsRepeater" runat ="server">
            <ItemTemplate>
                <tr>
                    <td>
                    <Shb:PartPaymentOptionIsCampaign ID="PartPaymentOptionIsCampaign" runat="server">
                    <OnTrue>
                            <b>
                            <Shb:PartPaymentOptionName runat ="server" />
                            </b>
                    </OnTrue>
                    <OnFalse>
                        <Shb:PartPaymentOptionName runat ="server" />
                    </OnFalse>
                    </Shb:PartPaymentOptionIsCampaign>                        
                    </td>
                    <td>
                        <Shb:PartPaymentOptionAdminFee DisplayCurrencySymbol="true" runat ="server" />
                    </td>
                    <td>
                        <Shb:PartPaymentOptionCampaignFee DisplayCurrencySymbol="true" runat ="server" />
                    </td>                    
                     <td>
                        <Shb:PartPaymentOptionMaxAmount DisplayCurrencySymbol="true" runat ="server" />
                    </td>
                     <td>
                        <Shb:PartPaymentOptionMinAmount DisplayCurrencySymbol="true" runat ="server" />
                    </td>
                     <td>
                        <Shb:PartPaymentOptionMinLimit DisplayCurrencySymbol="true" runat ="server" />
                    </td>                    
                     <td>
                        <Shb:PartPaymentOptionDescription runat ="server" />
                    </td>
                     <td>
                        <Shb:PartPaymentOptionOtherText runat ="server" />
                    </td>
                </tr>
            </ItemTemplate>
         </Shb:PartPaymentOptionRepeater>
         </table>
          <table class="ordertotals orderdata common">
         <tr>
         <td><b>Part payment option</b></td>
         <td><b>Interest rate %</b></td>
         <td><b>Effective Interest rate %</b></td>
         <td><b>No of payments</b></td>
         <td><b>Monthly payment</b></td>
         <td><b>Credit cost</b></td>
         <td><b>Total cost</b></td>
         </tr>
         
         <Shb:PartPaymentOptionRepeater ID="PartPaymentOptionRepeater1" runat ="server">
            <ItemTemplate>
                <tr>
                    <td>
                    <Shb:PartPaymentOptionIsCampaign ID="PartPaymentOptionIsCampaign" runat="server">
                    <OnTrue>
                            <b>
                            <Shb:PartPaymentOptionName runat ="server" />
                            </b>
                    </OnTrue>
                    <OnFalse>
                        <Shb:PartPaymentOptionName runat ="server" />
                    </OnFalse>
                    </Shb:PartPaymentOptionIsCampaign>                        
                    </td>
                     <td>
                        <Shb:PartPaymentOptionInterestRate runat ="server" /> %
                    </td>
                    <td>
                        <Shb:PartPaymentOptionEffectiveRate runat ="server" /> %
                    </td>
                     <td>
                        <Shb:PartPaymentOptionPayments runat ="server" />
                    </td>
                     <td>
                        <Shb:PartPaymentOptionPerMonth runat ="server" />
                    </td>     
                     <td>
                        <Shb:PartPaymentOptionCreditCost runat ="server" />
                    </td>
                     <td>
                        <Shb:PartPaymentOptionTotalCost runat ="server" />
                    </td>                  
                </tr>
            </ItemTemplate>
         </Shb:PartPaymentOptionRepeater>
         </table>
    </Ecom:ShoppingCartPanel>


</asp:Content>

Webcontrol to set "Use existing account" when paying by account

When paying by account, there is an option to select an existing account of the customer. To allow customers to choose, simply place following webcontrol in the checkout flow, idealy just before the buy button. Note that the control should be inside a Ecom:ShoppingCartPanel (or any webcontrol that is a IOrderCarrierIntroducer)

 <shb:PayWithExistingAccount runat="server" />

Displaying list of part payment options in a drop down

Apart from using the PartPaymentOptionRepeater shown in the above example, you may use the following webcontrol to show a drop down list of Handelsbanken Ecster campaigns.

<shb:PartPaymentOptionsDropDownList runat="server" />

Note that the control should be inside a Ecom:ShoppingCartPanel (or any webcontrol that is a IOrderCarrierIntroducer)

Get address from person number

Handelsbanken provider support getting address from person number, however this function will only work with Live accounts, not in test mode.

Call the following method in HandelsbankenFinansProvider class, with person number and the Zip code of the customer. It returns a address carrier with the address information.

        /// <summary>
        /// Get address of the person with <paramref name="customerPersonalNumber"/>
        /// </summary>
        /// <param name="customerPersonalNumber">The customer personal number.</param>
        /// <param name="zip">The zip.</param>
        /// <param name="paymentAccountIdentifier">The payment account identifier.</param>
        /// <returns></returns>
        public static AddressCarrier GetAddress(string customerPersonalNumber, string zip, string paymentAccountIdentifier = null)

Example:

Assume that TextboxSSN contains a customer social security number and TextboxAddressZip contains the zip code.

                   Litium.Foundation.Modules.ECommerce.Carriers.AddressCarrier addressCarrier
                        = HandelsbankenFinansProvider.GetAddress(TextboxSSN.Text, TextboxAddressZip.Text);

Synchronization of states

In cases where there is a mismatch between Litium Studio payment status and Handelsbanken transaction status, the Synchronize button in the payment view of Litium Studio backoffice can be used. It will fetch the status from Handelsbanken and synchronize Litium Studio payment status with it.