FlexWin (Method 1)

Handelsbanken Finans

Parameters specific for invoice payments

Short example for basic overview.

Parameters marked [parameter] are optional.

All parameters specified below only has effect for invoice payments, except the ‘orderid’ and ‘paytype’ parameters that are also available in the standard Flexwin integration applicable for various payment methods.

Parameter	Type	Description
amount	long - Minimum value of 1	Amount of transaction in smallest unit. Used to validate against prices in structured orderInformation.
accepturl	string. No max length	The URL of the page to be displayed if the purchase is approved.
orderid	string. Max 16 characters	For invoice payments the orderid is limited to 16 characters
currency	string. 3 digits or 3 letters	Currency specification as indicated in ISO4217 where the EUR is no. 978. Either the numeric or alphabetic code is accepted. Also see our list of currencies.
email (optional, but strongly recommended to always provide)	string	This is the customer's email address. It is strongly recommended to always provide this information to DIBS for all invoice payment methods. The invoice service providers may use the customer’s email address for sending the customer information regarding that a credit rating check has taken place (depending on the regulations in different markets/countries). When using invoice payments the email parameter is also used for sending the invoice to the customer if “distrbutionType=email”.
structuredOrderInformation	string	This is a string which specifies order information. E.g., the items purchased and their quantity, item description, unit price, sum total, etc., all formatted in XML. See detailed information below.
[billingFirstName]	string	Customer's billing first name.
[billingLastName]	string	Customer's billing last name.
[billingAddress]	string	Customer's billing street address. If acquirer doesn't support getAddress but requires user to enter some billing address information, this parameter can be used to prepopulate values on IW 1st page/or set values on merchant's/legacy system's side. If acquirer returns appropriate value in getAddress/placeOrder - value from acquirer will override value sent in this parameter.
[billingAddress2]	string	Customer's billing street address (continued).
[billingPostCode]	string	Customer's billing postal code
[billingPostalPlace]	string	Customer's billing postal place (city, town, etc).
[shippingFirstName]	string	Customer's first name.
[shippingLastName]	string	Customer's last name.
[shippingAddress]	string	Customer's shipping street address. If acquirer supports delivery to address specified by merchant (different from registered on acquirer), this parameter should be used.
[shippingAddress2]	string	Customer's shipping street address (continued).
[shippingPostCode]	string	Customer's shipping postal code.
[shippingPostalPlace]	string	Customer's shipping postal place (town, city, etc.).
[shippingFee]	string	Shipping Fee (expressed in smallest unit of currency).
[ShippingFeeVAT]	string	Shipping Fee VAT (e.g. "25%" is expressed as "2500"), must be filled if shippingFee is present.
[customerIpAddress]		Customer's IP address.
[merchantName]	string	Merchant's name to be displayed. Default is read from the merchants Dibs agreement.
[invoiceFee]	number	Invoice fee (expressed in minor unit of currency).
[invoiceFeeVAT]	number	Invoice Fee VAT (e.g. "25%" is expressed as "2500"), must be filled if invoiceFee is present.
[paytype]	string. max 30 characters	Used to show and control the shops selection of payment methods in Flexwin. This list must be comma separated with no spaces in between. Example: <input type="hidden" name="paytype" value="VISA,MC,AMEX,MTRO,ELEC" /> See our list of possible paytypes.
[customerId]	string	If the shop holds IDs (customer numbers) for it’s customers this information should be passed to the invoice service provider using this parameter. The customerId is limited to 20 characters. If no customerId is provided some invoice service providers generate a new customerId which can be fetched via a FlexWin return parameter. For more details see the ‘return values’ section below.
[createInvoiceNow]		Specifies whether the invoice is to be created in direct connection to the order placement. This functionality can be used if the order is to be shipped automatically upon order creation. Allowed values: true, false. Default: false.
[distributionType]		Defines on which media should the bill be sent to the customer. If the value ‘notset’ is declared the invoice will not be sent and the merchant must send the invoice manually. Allowed values: email , paper, notset (default)
[orgno]	number	Organization number. If not sent as input parameter to FlexWin, the customer may be prompted for it in the DIBS invoice payment flow (invoice window).
[doNotShowLastPage]		Whether to show the receipt page (last page) in the DIBS invoice payment flow (invoice window). Allowed values: true, false. Default: false. Strongly recommended to use value true to reduce steps needed for customer to return to Shop.
[ssn]	number	Social security number. If not sent as input parameter to FlexWin, the customer may be prompted for it in the DIBS invoice payment flow (invoice window).
[zip]		The customer’s registered postal/zip code. If not specified, the customer may be prompted for it in the Dibs invoice payment flow.
[round]	boolean	input type= true or false Performs round for order or not. Default false.

Structured order information

Please notice that the contents of the parameter structuredOrderInformation needs to be UTF-8 and HTML-encoded. Below is a short example of the same parameter before and after HTML encoding.

Plain text

<?xml version="1.0" encoding="UTF-8"?><orderInformation> <orderItem itemDescription="prod1" itemID="3363" orderRowNumber="1" price="400" quantity="1" unitCode="pcs" VATPercent="0" /></orderInformation>

HTML encoded

Below are the parameters for the structured order information.

Parameter	Description
orderItem	Each item in the order is specified by an orderItem tag. The item is described through a list of attributes listed below. • orderRowNumber (required): Each item is numbered, starting with 1 and then incremented sequentially. Items are sorted according to this sequence. As a consequence, items may be listed in any order inside the parameter structuredOrderInformation. • itemID (required): The shop's ID of the item. • itemDescription (required): A textual description of the item. Maximum length is 255 characters. • unitCode (required): The quantity unit of the item, e.g. kg, liter, etc. • quantity (required): The number of items, or the quantity of units. • price (required): The price of 1 unit excl. VAT in the smallest currency unit, e.g. 100 for 1 NOK or SEK. Please notice: Either VATPercent or VATAmount must be declared for each order line. • VATAmount (optional): VAT as a specific amount in the smallest currency unit. The amount corresponds to one (1) quantity of the item. If declaring VATAmount, you must calculate the VAT amount and pass the amount through to DIBS. • VATPercent (required): VAT as a percentage times 100. E.g. the value 1500 corresponds to 15%. The VAT amount must be specified and declared, either as VATPercent or VATAmount If declaring VATPercent, DIBS automatically calculates the VAT amount based on the transaction amount + VAT percentage submitted. If you declare VATPercent, the calculation is made like this: - Every order row sum is calculated as Round (Quantity * Round(ItemAmount * VatPercent)). Rounding of (ItemAmount * VatPercent) and rounding of total order row sum is done using 2 decimals. - Total order sum for the whole order is calculated as the sum of all the rounded order row sums (as decribed above). Example: <orderitem itemdescription="prod1" itemid="3363" orderrownumber="1" price="3599" quantity="13" unitcode="pcs" vatpercent="2500"> (3599 * 1.25) * 13 = 4498.75 ? 4499 *13 = 58487</orderitem>
[comments]	The place for any additional comments.

Special characters

Special characters as < > & ” ’ are not valid in XML data and cannot be used. More information can be found here. We recommend that you convert these characters to:

< : <
> : >
' : '
" : "
& : &

To use characters like å, ä, ö you need to use the character entities i.e

å = å
Å = Å
ä = ä
Ä = Ä
ö = ö
Ö = Ö
æ = æ
Æ = Æ
ø = ø
Ø = Ø

More entities can be found here. More information on FlexWin and charsets as well as example PHP code of how to rewrite data chars and charsets can be found in the zip file provided in the examples section at the bottom of this page.

Return values

Returns from Flexwin are described in general under return pages. In addition to the normal return parameters you will receive the invoice specific values listed below.

Please note:

Some of the return values are only returned to callbackurl, not to accepturl, which means you need to use the callback functionality for all invoice payment methods.
You need to enable the return of all CGI variables in DIBS Admin under Integration > Return Values. (check all the boxes)

Normally, it is a requirement from the invoice service providers that that shipment of goods is made to the customers registered address and not any other address.The customers registered address is the address returned from FlexWin to the shop via some of the parameters specified in the table below.

Parameter	Description
lastName	Customer's last or company name from national registry. Please notice: For Handelsbanken Finans Invoice the full name of the customer is returned in the lastName parameter.
customerId	Customer id / Customer number
deliveryAddress	Delivery address from national registry. Normally, the goods have to be delivered to the address returned here.
deliveryCountryCode	Customer's country code returned by acquirer, e.g.‘SE’.
deliveryPostalCode	Delivery postal code from national registry
deliveryPostalPlace	Delivery postal place from national registry
invoiceId	Invoic id in SHB's database.
creditLimit	Indicates credit limit of customer.
round	Indicates wether rounding was used in this invoice.

Discounts

Discounts are specified as normal order items but with negative prefix for both the price and the VAT parameter values. VAT must be specified either as VATAmount or VATPercent.

Important:
Handelsbanken Finans allows only VAT percentage equal to 0, 6, 12 and 25% - all other values will be rejected.

For more details on how to specify order items see the order item parameter description above.

Invoice fees

Invoice fees may be added to the transactions by either:

Option 1.

Invoice fee as a separate order line in your webshop posted to DIBS as part of the transaction amount. This requires the use of the paytype parameter to ensure that the fee is added only for invoice transactions since the ‘amount’ parameter value sent to FlexWin will need to include the fee amount. This solution makes it impossible to provide anything but invoice payment methods to the customer in DIBS FlexWin, This is because other payment methods must probably not be affected by the invoice fee. Please refer to this document, point 9 for further information.

Option 2.

Only available for some invoice service providers. Invoice fee added in the invoice service provider’s system. Please contact your invoice service provider directly for more details.

Testing

To activate test mode for any invoice payment method you need to send a test parameter along with the post parameters.<input type="hidden" name="test" value="foo" />.
General invoice test information can be found here.

If you cannot see the invoice payment method as an option in DIBS FlexWin when sending the test parameter it most likely means that the test functionality is not activated in DIBS backend and you should contact DIBS support according to the contact details below.
Please contact our support via one of the following links regarding any integration issues.
Denmark http://help.dibs.dk
Norway http://help.dibs.no
Sweden http://help.dibs.se

Debugging / Technical Integration Issues

Whitescreen: If a whitescreen appears, this is usually because the parameter ‘structuredOrderInformation’ is missing or caused by a syntax error in the XML file. The syntax of the XML file can be validated using XML DOM Validation: http://www.w3schools.com/dom/dom_validate.asp

Technical error: Common reasons if this error message appears is logical errors such as error in the calculation of VAT amount or total order sum. If an error occurs, you can normally find a detailed error description via a link from the error page that appears.

Recommendation

It is recommended to reduce the number of clicks/steps needed for the customer to return to the shop after payment is fullfilled by using both of the two following methods.

In DIBS Administration, Integration, Flexwin check the " Skip accept page" checkbox. Please note that if this method is used the accept-url redirect to the web shop from FlexWin will be a GET request.Use the doNotShowLastPage = true described in the list paramater list above.

Examples

The ZIP file below consists of two complete and fully working examples for integrating DIBS Invoice payment methods. The zip file also contains useful information regarding charset handling.

DIBS Invoice examples

FlexWin (Method 1)

Handelsbanken Finans

Parameters specific for invoice payments

Parameter

Type

Description

Structured order information

Plain text

HTML encoded

Parameter

Description

Special characters

Return values

Please note:

Parameter

Description

Discounts

Invoice fees

Option 1.

Option 2.

Testing

Debugging / Technical Integration Issues

Recommendation

Examples