Invoice parameters

When using Invoice payments, some additional parameters have to be sent to Nets. 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

Parameter Type Description
createInvoiceNow String 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.
customerId String If 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.
customerIpAddress String Customers IP address.
doNotShowLastPage String Whether to show the receipt page (last page) in the Nets 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 * Integer Invoice fee (expressed in minor unit of currency).
invoiceFeeVAT * Integer Invoice fee VAT (e.g. "25%" is expressed as "2500"), must be filled if invoiceFee is present.
merchantName String Merchant's name to be displayed. Default is read from the merchants Nets agreement.
notificationUrl String

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
orgno Integer Organization number. If not sent as an input parameter to FlexWin, the customer may be prompted for it in the Nets invoice payment flow (invoice window).
pclass ** String Campaign code. Indicates campaign used in part payments/installments.
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).
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.
shippingFirstName String Customer's first name.
shippingLastName String Customer's last name.
shippingPostalCode String Customer's shipping postal code.
shippingPostalPlace String Customer's shipping postal place (town, city, etc.).
ssn Integer Social security number. If not sent as input parameter to FlexWin, the customer may be prompted for it in the Nets invoice payment flow.
ysalary ** String Customers yearly salary – specified in ore or cents.
zip *** String Customers registered postal/zip code. If not specified, the customer may be prompted for it in the Nets 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 a question or need help?
Follow us
Nets Online Payments

Oslo: +47 21 55 44 00
Stockholm: +46 (0)8-527 525 00
København: +45 7020 3077
Jyväskylä: + 358 010 80 40 40
Close menu