Invoice parameters

When using Invoice payments, some additional parameters have to be sent to DIBS. These parameters include the products and the prices of these products. This makes it possible for the invoice acquirer to make a precise invoice to the customer

Essential

Below is a list of the mandatory parameters for invoice acquirers in addition to the essential parameters.

ParameterTypeDescription
distributionType * Defines on which media the bill should 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)
structuredOrderInformationString

This is a string which specifies order information.

See detailed information of the syntax further down this page.

* : Required by Klarna, optional for everyone else

Optional

ParameterTypeDescription
createInvoiceNowStringSpecifies 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.
customerIdStringIf the shop holds IDs (customer numbers) for its customers this information should be passed to the invoice service provider using this parameter. It has a maximum length of 20 chars.
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.
customerIpAddressStringCustomers IP address.
doNotShowLastPageStringWhether to show the receipt page (last page) in the DIBS invoice payment flow (invoice window).
Allowed values: true, false. Default: false.
Strongly recommended to set the value to "true" to reduce the steps needed for the customer to return to the shop.
invoiceFee *IntegerInvoice fee (expressed in minor unit of currency).
invoiceFeeVAT *IntegerInvoice fee VAT (e.g. "25%" is expressed as "2500"), must be filled if invoiceFee is present.
merchantNameStringMerchant's name to be displayed. Default is read from the merchants DIBS agreement.
notificationUrlString

If this parameter is sent, a "server-to-server" call will be made when the payment changes status from "postponed" (26) to "capture approved" (5), "authorization approved" (2) or "authorization declined" (1).

Example:

htts://www.mydomain.com/paymentReturn/notification
orgnoIntegerOrganization number. If not sent as an input parameter to FlexWin, the customer may be prompted for it in the DIBS invoice payment flow (invoice window).
pclass **StringCampaign code. Indicates campaign used in part payments/installments.
shippingAddressStringCustomer's shipping street address. If acquirer supports delivery to address specified by merchant (different from registered on acquirer), this parameter should be used.
shippingAddress2StringCustomer's shipping street address (continued).
shippingFeeStringShipping Fee (expressed in smallest unit of currency).
shippingFeeVATStringShipping Fee VAT (e.g. "25%" is expressed as "2500"), must be filled if shippingFee is present.
shippingFirstNameStringCustomer's first name.
shippingLastNameStringCustomer's last name.
shippingPostalCodeStringCustomer's shipping postal code.
shippingPostalPlaceStringCustomer's shipping postal place (town, city, etc.).
ssnIntegerSocial security number. If not sent as input parameter to FlexWin, the customer may be prompted for it in the DIBS invoice payment flow.
ysalary **StringCustomers yearly salary – specified in ore or cents.
zip ***StringCustomers registered postal/zip code. If not specified, the customer may be prompted for it in the DIBS invoice payment flow.

* : Not used by Klarna
** : Klarna only
*** : Only used by PayByBill and Handelsbanken Finans

Structured order information

The parameter "structuredOrderInformation" is used to build the invoice contents, such as the description, quantity and amount of the goods sold. This parameter is mandatory if the shop wants to accept invoice payments.

To constuct the structured order information the following parameter is required.
See the bottom of the page for examples.

Each item in the order is specified by an orderItem tag. The item is described through a list of attributes listed below.

ParameterTagsDescription
orderItemitemIDThe shop's ID of the item.
itemDescriptionA textual description of the item. Maximum length is 255 characters.
unitCodeThe quantity unit of the item, e.g. kg, liter, etc.
quantityThe number of items, or the quantity of units.
priceThe price of 1 unit excl. VAT in the smallest currency unit, e.g. 100 for 1 NOK or SEK.
VATAmount

Either VATPercent or VATAmount must be declared for each order line.

VATAmount is in the smallest currency unit. The amount corresponds to one (1) quantity of the item.
VATPercent is the percentage times 100. E.g. the value 1500 corresponds to 15%.

If declaring VATPercent, DIBS will calculate the VAT amount based on the price, quantity and VATPercent as follows;
- Every order row is calculated as Round (Quantity * Round(ItemAmount * VatPercent)). Rounding 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 described above).

Example.
<orderitem itemdescription="prod1" itemid="3363" orderrownumber="1" price="3599" quantity="13" unitcode="pcs" vatpercent="2500"></orderitem>
Total row amount is: (3599 * 1.25) * 13 = 4498.75 ? 4499 *13 = 58487

VATPercent

The price of all the orderItems has to be the same as the amount submitted through the essential parameters.

These parameters can be used to add more information about the purchase, that is sent to the invoice company.
See the bottom of the page for examples.
 

ParameterDescriptionUsed by
comments

Used if any additional comments should be added.

All
exchangeRateThis specifies the currency exchange rate.PayByBill
statCodeNum

Numerical code used for labelling orders, e.g., the code of the seller who handled the order. Used for statistical purposes.

All except Handelsbanken
statCodeAlphaNumTextual code used for labelling orders, e.g., the code of the seller who handled the order. Used for statistical purposes.All except Handelsbanken
ourRef

 The shop's order reference.

All except Handelsbanken
yourRef

The customer's order reference.

All except Handelsbanken

 

Since special characters are not allowed in XML, the following conversions should to be used, if special characters are used in the order information.
 

<&lt;
>&gt;
'&apos;
"&quot;
&&amp;
ä&auml;
Ä&Auml;
ö&ouml;
Ö&Ouml;
æ&aelig;
Æ&AElig;
ø&oslash;
Ø&Oslash;
å&aring;
Å&Aring;

More entities can be found here.
 

Please notice that the content of the parameter structuredOrderInformation needs to be UTF-8 and HTML-encoded.
See the bottom of the page for examples.

Invoice examples

<form name="payform" method="post" action="https://payment.architrade.com/paymentweb/start.action">
  <input type="hidden" name="accepturl" value="http://www.yourshop.com/payment_accepted.html" />
  <input type="hidden" name="amount" value="400" />
  <input type="hidden" name="billingAddress" value="customer_billing_adress" />
  <input type="hidden" name="billingAddress2" value="customer_billing_adress_continued" />
  <input type="hidden" name="billingFirstName" value="customer_billing_first_name" />
  <input type="hidden" name="billingLastName" value="customer_billing_last_name" />
  <input type="hidden" name="billingPostalCode" value="customer_billing_postal_code" />
  <input type="hidden" name="billingPostalPlace" value="customer_billing_postal_place" />
  <input type="hidden" name="cardholder_name" value="cardholder_name" />
  <input type="hidden" name="currency" value="752" />
  <input type="hidden" name="distributionType" value="way_of_billing_the_costumer" />
  <input type="hidden" name="email" value="costumer_email" />
  <input type="hidden" name="md5key" value="calculated_md5_key" />
  <input type="hidden" name="merchant" value="your_DIBS_merchant_id" />
  <input type="hidden" name="orderid" value="your_order_id" />
  <input type="hidden" name="structuredOrderInformation" value="&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&lt;orderInformation&gt; &lt;orderItem itemDescription=&quot;prod1&quot; itemID=&quot;3363&quot; orderRowNumber=&quot;1&quot; price=&quot;400&quot; quantity=&quot;1&quot; unitCode=&quot;pcs&quot; VATPercent=&quot;0&quot; /&gt;&lt;/orderInformation&gt;">
  <input type="submit">
</form>

This example shows how the calculation of the total price of all orderItems is executed when using structuredOrderInformation
 

<?xml version="1.0" encoding="UTF-8"?>
    <orderInformation>
        <orderItem VATAmount="100" itemDescription="small bike" itemID="1234" orderRowNumber="1" price="100" quantity="1" unitCode="pcs"/> <!-- Total price incl. VAT = 200-->
        <orderItem VATPercent="2500" itemDescription="big bike" itemID="4321" orderRowNumber="2" price="200" quantity="4" unitCode="pcs"/> <!-- Total price incl. VAT = 1000-->
    </orderInformation>

<!-- The amount submitted through the essential parameters has to be 1200 -->

 

This example shows how the additional parameters are used in the total structuredOrderInformation.

<?xml version="1.0" encoding="UTF-8"?>
    <orderInformation>
        <exchangeRate>0.0</exchangeRate>
        <ourRef>ourRef123</ourRef>
        <yourRef>yourRef123</yourRef>
        <statCodeNum>1234</statCodeNum>
        <statCodeAlphaNum>statCodeAlphaNum</statCodeAlphaNum>
        <comments>some order comments</comments>
        <orderItem VATPercent="1000" itemDescription="suzuki red bike" itemID="1234" orderRowNumber="1" price="200" quantity="1" unitCode="pcs"/>
        <orderItem VATAmount="100" itemDescription="bmw blue bike" itemID="1234" orderRowNumber="2" price="300" quantity="1" unitCode="pcs"/>
    </orderInformation>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&lt;orderInformation&gt;&lt;exchangeRate&gt;0.0&lt;/exchangeRate&gt;&lt;ourRef&gt;ourRef123&lt;/ourRef&gt;&lt;yourRef&gt;yourRef123&lt;/yourRef&gt;&lt;statCodeNum&gt;1234&lt;/statCodeNum&gt;&lt;statCodeAlphaNum&gt;statCodeAlphaNum&lt;/statCodeAlphaNum&gt;&lt;comments&gt;some order comments&lt;/comments&gt;&lt;orderItem VATPercent=&quot;1000&quot; itemDescription=&quot;suzuki red bike&quot; itemID=&quot;1234&quot; orderRowNumber=&quot;1&quot; price=&quot;200&quot; quantity=&quot;1&quot; unitCode=&quot;pcs&quot;/&gt;&lt;orderItem VATAmount=&quot;100&quot; itemDescription=&quot;bmw blue bike&quot; itemID=&quot;1234&quot; orderRowNumber=&quot;2&quot; price=&quot;300&quot; quantity=&quot;1&quot; unitCode=&quot;pcs&quot;/&gt;&lt;/orderInformation&gt;
<?xml version="1.0" encoding="UTF-8"?>
	<orderinformation>
		<orderitem itemdescription="product ÆØÄ" itemid="3363" orderrownumber="1" price="400" quantity="1" unitcode="pcs" vatpercent="0">
		</orderitem>
	</orderinformation>
<?xml version="1.0" encoding="UTF-8"?>
	<orderinformation>
		<orderitem itemdescription="product &AElig;&Oslash;&Aring;" itemid="3363" orderrownumber="1" price="400" quantity="1" unitcode="pcs" vatpercent="0">
		</orderitem>
	</orderinformation>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&lt;orderInformation&gt; &lt;orderItem itemDescription=&quot;product &AElig;&Oslash;&Aring;&quot; itemID=&quot;3363&quot; orderRowNumber=&quot;1&quot; price=&quot;400&quot; quantity=&quot;1&quot; unitCode=&quot;pcs&quot; VATPercent=&quot;0&quot; /&gt;&lt;/orderInformation&gt;

This example shows how the encoding of special characters like for example "æøå" is done.

 

Do you have question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00