Essential
Below is a list of the mandatory parameters for invoice acquirers in addition to the essential parameters.
| Parameter | Type | Description |
|---|---|---|
| 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) | |
| structuredOrderInformation | String | 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 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 * | 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 DIBS 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 DIBS 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 DIBS 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 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.
| Parameter | Tags | Description |
|---|---|---|
| orderItem | itemID | The shop's ID of the item. |
| itemDescription | A textual description of the item. Maximum length is 255 characters. | |
| unitCode | The quantity unit of the item, e.g. kg, liter, etc. | |
| quantity | The number of items, or the quantity of units. | |
| price | The 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. | |
| 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.
| Parameter | Description | Used by |
|---|---|---|
| comments | Used if any additional comments should be added. | All |
| exchangeRate | This 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 |
| statCodeAlphaNum | Textual 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.
| < | < |
| > | > |
| ' | ' |
| " | " |
| & | & |
| ä | ä |
| Ä | Ä |
| ö | ö |
| Ö | Ö |
| æ | æ |
| Æ | Æ |
| ø | ø |
| Ø | Ø |
| å | å |
| Å | Å |
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="<?xml version="1.0" encoding="UTF-8"?><orderInformation> <orderItem itemDescription="prod1" itemID="3363" orderRowNumber="1" price="400" quantity="1" unitCode="pcs" VATPercent="0" /></orderInformation>"> <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>
<?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>
<?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 ÆØÅ" 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 ÆØÅ" itemID="3363" orderRowNumber="1" price="400" quantity="1" unitCode="pcs" VATPercent="0" /></orderInformation>
This example shows how the encoding of special characters like for example "æøå" is done.