Page Sets

The page sets are the pages defining how the payment window will look and behave. This page contains information regarding how to configure the page sets.

Introduction

The consumer must complete the payment details at pages hosted on the DIBS server, and he can also complete his personal details there. The handling of these page sets is done using the DIBS Manager.

In all DIBS pages, special commands can be used, for example, for displaying the content of the parameters that the shop transmits to DIBS. Certain special commands also replace HTML code. DIBS commands are always started and terminated with square brackets “[” and “]”. These commands are described below.

Page sets

One or several page sets can be used per shop if, for example, a shop uses different languages or different payment methods. Each group of pages and reports is called a page set. There are several templates for page sets available in DIBS Manager that you can use as a starting point for your page set development.

Going to Hosted pages > Overview, you get a table showing all page sets. A cross in the table indicates that the page exists.

Adding web pages

To add page sets press Hosted pages > Overview > Add a new page set. Here you can select one or more template page sets that have been especially created for different payment methods or you can create your own (custom) page set. The templates should be modified by the shop so they comply with the shop’s own web pages. Note that a lot of useful comments exist in the template pages.

Editing web pages

There are four form pages (Page 1 – Page 4) on Hosted pages > Overview > edit that can be used for retrieving and displaying desired information at DIBS for the consumer. For each of the four pages, there is a return page to handle incorrectly entered information, such as expiry date or an incorrect card number. In addition, there are special pages for approved (OK) or declined authorization, and whether the order exceeds the maximum sum set in Security > Overview > Amount limit

When a page is saved, which is done by pressing the Save button, the form(-s) is/are in a test version of the system. This means that they can be called using the Hosted pages > Test Purchase. To transfer the test version to live operation, e.g. for doing tests from outside the DIBS Manager, you must select Hosted pages > Set in service.

Note that the HTML form tags <FORM ACTION=””> and </FORM> in the DIBS forms are to be replaced by [ver formstart] and [ver formend] respectively, to send information between the form pages. Note also that the command [ver verify] has to be entered to execute verification when all necessary details have been acquired. Let’s assume that all address details are sent from the shop – only card number and expiry date are completed at DIBS. The resulting HTML code may then have the following appearance:

...
[ver formstart]
Credit card number <INPUT TYPE="text" NAME ="cc"><BR >
Expiry date
<INPUT TYPE="text" NAME ="exp M" SIZE=”2”> /
<INPUT TYPE="text" NAME ="expY" SIZE=”4”><P >
<INPUT TYPE="sub mit" NAME ="Send card info">
[ver formend]
...

The HTML code in the example above is quite unformatted. Naturally, it is possible to insert code into a table, or similar, thus creating a neater page.

Note that external components (e.g. “stylesheets” or images) should not be linked to from the DIBS pages since this leads to a warning message being displayed to the consumer about the secure DIBS page containing insecure material. Use Hosted pages > Images to load images to DIBS, which you can subsequently link to from the DIBS pages. Of course you can use “style sheets” on each of your DIBS pages, as long as they’re not linked to servers outside DIBS.

Deleting web pages

To delete a page sets click the Hosted pages > Overview > Delete link.

The page sets in test mode

When a page has been saved by pressing the Save button, the forms are on the test version of the system. In this way, the pages can be changed and tested without showing the changes to the consumer. Using the test version of the system means that they can be called using the Hosted pages > Test purchase, with the parameters given in Hosted pages > Test parameters.

Parameter values

The [ver valueof=”…”] command returns the value of the parameter entered. Parameters are sent to DIBS via an HTML form or are entered on the DIBS pages.

If a form contains these:

<input name="Name" size="38" type="TEXT">
<input name="City" size="38" type="TEXT">

The parameters can then be retrieved with the following values from the DIBS form pages (or in reports, for example):

[ver valueof=”Name”]
[ver valueof=”City”]

An example of a DIBS form is included below. The text between [ver table start] and [ver table end] is repeated once per item type in the order.

...
[ver table start]
Item_no: [ver table art no]<BR>
Name: [ver table description]<BR>
Quantity: [ver table number]<BR>
Price: [ver table price]<BR>
Tot: [ver table total price]<BR>
[ver table end]
-----<BR>
Total: [ver sum]<BR>
...

Assume that the consumer has ordered 2 t-shirts and a baseball cap. Then, the above will result in the following HTML code:

...
Item_no: 1<BR>
Name: T-shirt<BR>
Quantity: 2<BR>
Price: 14,95<BR>
Tot: 29,90<BR>
Item_no: 2<BR>
Name: Baseball cap<BR>
Quantity: 1<BR>
Price: 9,95<BR>
Tot: 9,95<BR>
-----<BR>
Total: 39,85<BR>
...

The following table lists all the possible tags/parameters which DIBS will replace in the page sets.

Function Command Description
Form [ver formstart] Starts the form (instead of <form action=”…”>).
[ver formend] Terminates the form (instead of </form>).
[ver expM] Adds a <select> called ”expM” with possible values ”01,02...12”.
[ver expY] Adds a <select> called ”expY” with values starting from the current year and 10 years ahead.
Parameter value [ver valueof=”…”] Returns the value of the given parameter (such as are specified by DIBS and those defined by the shop itself, such as “trolleyId”).
[ver valueof html=”…”] Returns HTML coded parameter value.
[ver valueof url=”…”] Returns URL-coded parameter value.
System parameter value [ver sysinfo=”…”] Returns the value of the given system parameter (as described in the section System parameter values below).
Stock item data [ver table start] Starts iteration of the items in the data parameter.
[ver table end] Terminates iteration.
[ver table art no] Returns stock item number for the current item.
[ver table art no html] Returns HTML coded stock item number.
[ver table art no url] Returns URL-coded stock item number.
[ver table description] Returns stock item description of the current item.
[ver table description html] Returns HTML coded stock item description.
[ver table description url] Returns URL-coded stock item description.
[ver table number] Returns the quantity of the current item.
[ver table price] Returns the unit price of the current item. (The decimal point is represented by a comma.)
[ver table total price] Returns the total price of the current item. (The decimal point is represented by a comma.)
Total sum [ver sum] Returns the total for all ordered items. (The decimal point is represented by a comma.)
Conditional statements [ver if …]

Starts a conditional statement. The given expression can be in one of the following formats:

Parameter == ”value”

”value” == parameter

parameter != ”value”

”value” != parameter

Note that conditional statements cannot be nested (i.e. one conditional statement cannot contain another).

[ver else] Starts an alternative statement to a conditional statement.
[ver endif] Terminates a conditional statement.
Date and time [ver date=”…”] Returns the current date and time in the stated format using the following field codes: Year = yyyy or yy, month = mm, day = dd, hours = HH, minutes = MM, seconds = SS. E.g.: [ver date=dd/mm/yy] returns 31/12/15.
Check statement on return page [ver check=”…”]

Introduces a check statement which is executed if/when the given parameter has an invalid value. 

E.g.: [ver check=”eMail”] The e-mail address given was not correct. [ver endcheck] Used on return pages only. 

Note that if no check statement needs to be executed, the return page is not called either.

[ver endcheck] Terminates a check statement.
Execute verification [ver verify] Starts verification. Entered when all necessary parameters have valid values.
Reply from verification [ver reply] Returns “A” for approved and “D” for denied verification. Can be used in eventual HTTP report.
[ver reply text]

Returns a more detailed reply, that can be used for troubleshooting. Mainly for use on the result page.

"verification denied"

"timeout"

"no connection to bank server"

"this shop is not allowed to use the given currency"

"faktura ok" (Only invoices)

"server error (contact Verifyeasy)"

"timeout (2)" (no contact with acquirer)

"authentication denied" (For 3-D Secure payments)

"authentication timeout" (For 3-D Secure payments)

“customer check timeout”

“invoice timeout”

Redirection after verification [ver location=”…”]

Executes a redirection of the consumer, to the given URL. Used only on pages for approved or denied card check, respectively.

Note that the redirection takes place immediately if this command is included on the page, without the DIBS page being displayed, and that it therefore replaces any HTML code.

Please note: To protect yourself from fraud you need to use the MAC feature. Without the MAC, you cannot trust the redirect because a user who knows what he is doing can easily copy these requests.

E.g.: [ver location=http://www.store.se/order.asp?ordernumber=[ver id no]&Firstname=[ver valueof=billingFirstName]&status=[ver reply]&totalsum=[ver sum][ver MAC]]

Reference number [ver id no]

Returns the DIBS reference number, which is unique for each order. Must be included on all reports.

Used for any refund entry and must be entered on contact with DIBS customer support. (In test mode, the value “0” is returned).

Encrypted report [ver crypto=”…”]

Returns an encrypted report with optional parameter. The following format is used:

”Reference_number:Response:Amount:Currency:Parameter”

MAC [ver MAC]

Returns a MAC for the report. Note: For Http Reports and where redirection after verification is used, the MAC will be added by default (even if [ver MAC] is not used).

The following format is used:

”sum¤cy&reply&idno&[referenceData&]SecretKey&”

Properties [ver property ...]

The [ver property...] tag makes it possible to display text from a properties file (containing name=value pairs) that you have uploaded to the DIBS server.

A “ver property” tag has the following attributes:

1. key The name of the property

2. file The file name of the properties file to be used

3. default A default value to use if the property is not found (optional)

The key and file attributes are mandatory while the default attribute is optional. This example illustrates how to write this tag:

[ver property key=header file=examplefile.properties default=”Default Header”]

It is also possible to use a nested tag in order to make the property tag more dynamic. If you have sent in a parameter named “propertyFile”, then you could write the property tag like this:

[ver property key=header file=[ver valueof=propertyFile].properties default=”Default Header”]

URL Encode [ver urlencode text=”...”] URL encodes the content of text, so that the tag [ver urlencode text=”Text with spaces”] returns “Text+with+spaces”. The “text” attribute can contain nested [ver...] tags, for example [ver urlencode text=”[ver reply text]”]
3D Secure: Enrolled or not [ver 3dsenrolled]

Returns the response from the Directory Server that defines if the card is enrolled in 3D Secure or not. Possible values are:

“Y” - The card is enrolled and the cardholder has been sent to the card issuing bank.

“N” - The card is not enrolled and the payment processing has been continued with no further 3D Secure actions necessary.

“U” - The card is not eligible for 3D Secure processing, which means that the card may not be used with 3D Secure. No liability shift can be claimed for this card. The default behaviour of the DIBS system is to stop all further processing when receiving this response.

3D Secure: Authnticated or not [ver 3dsauthenticated]

Returns the result of a 3D Secure authentication (i.e., when the enrolment query has returned “Y”). Possible values are:

“Y”: The cardholder identified himself/herself correctly and the payment can continue with full 3D Secure protection.

“N”: The cardholder did not identify himself/herself correctly. The payment is aborted.

“A”: The issuer has registered the attempt to perform a full 3D Secure authentication, but no authentication has taken place. The payment can still continue with full 3D Secure protection.

 

System parameter values

The [ver sysinfo=”…”] command returns the value of the system parameter entered. You don’t send the system parameters to DIBS. DIBS provides them for you.

The parameters can then be retrieved with the following tag from the DIBS form pages (or in reports, for example):

[ver sysinfo=”ccPart”]

See the table below for all possible values

Parameter name Description

authCode

This system parameter contains the authorization code from the acquirer for card purchases. It is a code that the end-user might be interested in getting, especially if there is a problem with the purchase. Example of an authCode:

“897128”.

You can only retrieve the authCode for accepted authorizations; simply because it is only those that can have an authorization code.

acquirerResponseCode

This system parameter contains the acquirer's own, unfiltered, response code to a transaction request. These codes are mainly only applicable for credit card authorizations. The code is applicable for some other types of transactions as well. If it is it will be described in that context of the manual. You might be interested in this code as merchant if there was a problem with the transaction and you really want to know the acquirer's reason for declining the transaction.

ccPart

This system parameter enables you to get part of the card number used in the card purchase. The card number is cloaked in order to keep the real card number secret, e.g. “**** **** **** 1234”.

ccPrefix

This system parameter enables you to get the 6 first digits of the card number used in the card purchase. E.g. “491889”.

ccType

This system parameter enables you to get information about what type of card that was used in the card purchase. E.g. “Visa”, “MC”, “AmEx”, “DANCARD”, “MAESTRO”, “Resurs”, “Diners”, “MASTERCARD”, “ELECTRON”, “UNKNOWN”. This parameter is present where applicable.

ccCategory

This system parameter enables you to get information about what category of card that was used in the card purchase. E.g. “Diners”, “Resurs”, “AmEx”, “BANKKORT”, “P”, “MCC”, “J”, “B”, “MSI” and so forth. This parameter is present where applicable.

expM

This system parameter enables you to get information about the card expiry month used in the card purchase E.g. “03”.

expY

This system parameter enables you to get information about the card expiry year used in the card purchase E.g. “12”.

 

Properties

In some cases it may be useful to keep text that you want to display in a properties file. A properties file is a plain text file which contains name value pairs, one pair per row:

  • propertyname1=propertyvalue1
  • propertyname2=propertyvalue2

Save your file with the file extension ”.properties”. DIBS Manager has a file upload function under Hosted pages > Images > Upload your images. The image upload function can be used to upload any type of file as long as it is not too large.

Once you have the properties file uploaded to the DIBS server, you can access the properties in your page sets (and in Email and HTTP reports) using the following syntax:

[ver property key=propertyname1 file=myfile.properties default=”My default value”]

The default attribute is optional, while the key and the file attributes are mandatory. If you wish, you can use nested “ver” tags inside the property tag, so that you can make it more dynamic. For instance, you can choose to send in the name of the properties file as a parameter. If the parameter is named “fileName”, then you can use it this way:

[ver property key=propertyname1 file=[ver valueof=”fileName”] default=”My default value”]

Redirecting after verification

By typing [ver location=”http://YourURL/thanks.html”] into the Hosted pages > Overview > pageSet edit > authorization OK page, DIBS will redirect the consumer to the thanks.html page on your server (change the YourURL part) after successful verification. The equivalent can be done for authorization declined.

Please note that you can use this redirect as an automatic notification to your system that the payment was approved. However, for this to be safe you need to make use of the MAC functionality. Otherwise you make yourself vulnerable to fraud. You can read about MAC on the MAC page.

Internationalization

The simplest way of handling several languages in your page sets is to create one page set per language. However, it is also possible to use the properties file functions using the [ver property ...] tag described in the section above.

E-mail report

If desired, you may e-mail order confirmations to the consumers, and/or to other recipients chosen in advance. Usually there are different confirmations sent for approved and declined transactions, with the consumer and the shop as recipient. For the shop, DIBS strongly recommends the use of http reports, as DIBS can then check that the reports have actually reached its destination.

In e-mail reports, the same commands can be used as in the HTML forms. In the reports generated, the DIBS reference number should always be included. This is accomplished by entering the [ver id no] command in the message.

To create an e-mail report, click on Reports > E-mail, and then click on Add New E – mail report. An empty form is created for the e-mail report. Enter the page set that the report is to apply to (if you’ve got more than one page set) and the type of verification that the report is to be sent: OK, declined or in both cases. The following details must be completed on the form:

Field Content

address:

The e-mail address to which the message is being sent. Several e-mail addresses are separated by a comma (”,”). The message can thus be sent to several addressees. To insert the consumer’s e-mail address, the [ver valueof="eMail"] command is used.

sender:

The shop’s e-mail address, e.g. the shop’s Customer Relations.

subject:

The message header

message:

This is where you type the message. DIBS commands are permitted, of course.

For a start it may be a good idea to enter the shop’s e-mail address next to the consumer’s, in order for the shop to receive a copy of the confirmation.

HTTP report

For the shop, http reports are the most secure way of obtaining reports about payments. Using http reports, the shop can automate the entire payment process. The shop has a program (Servlet, JSP, ASP, or equivalent) on its web server, which receives and handles calls from DIBS after each order. When using the Test Purchase feature in DIBS Manager, http reports will not be sent but instead shown in a popup window.

To create an HTTP report click on Reports > HTTP. Then, choose Add new HTTP report and (Get) or HTTP (Post) as the report type, depending on how you want DIBS to call your server (GET sends data in the URL and POST sends data separately). An empty form is created for the http report. Enter the page set to which the report should be applied (if you’ve got more than one page set) and after which type of verification the report is to be sent: OK, declined or in both cases.

If you have chosen HTTP (Get), the URL field should contain the entire URL including the parameters with URL coding:

http://YourURL/ReceivingPage?DTrefNo=[ver id no]&reply=[ver reply]&sum=[ver sum]&firstname=[ver valueof url=”billingFirstName”]&lastname=[ver valueof url=”billingLastName”]

If you have chosen HTTP (Post), then enter the URL in a separate field. In the parameters field, enter one parameter per line on the form of “parameter name=parameter value”, with URL-coded values. URL:

http://YourURL/ReceivingPage

Parameters: (one parameter per line)

DTrefNo=[ver id no]

reply=[ver reply]

sum=[ver sum]

firstname=[ver valueof url=”billingFirstName”]

lastname=[ver valueof url=”billingLastName”]

Parameters that should be entered in the return report are “response” ([ver reply]), “total” ([ver sum]), “reference” ([ver id no]) and possibly a specific order number. In addition, name details should be included ([ver valueof url=”billingFirstName”] and [ver valueof url=”billingLastName”]).

When sending your parameter values, don’t forget to URL encode them (by using [ver table description url] for example).

To confirm that the report has been received, the reply page must somewhere contain the string “VerifyEasy_response:_OK”, e.g. as an html comment.

If this string is not included in the reply, e.g. due to temporary server overload, the system will retry sending the report (up to 25 times). If it has still not been received properly, we will send the report to the e-mail address you have entered in the e-mail field under the tab Reports > Http. If there is no value in this field the report will be e-mailed to the Administrator instead. The same applies if the call does not get through, perhaps due to network problems.

Some reasons for not receiving the http report:

  • Your firewall is not set to receive reports, from IP-address 217.151.192.130.
  • Your firewall is password protected
  • You’re trying to get the http report sent to an https-URL

Troubleshooting

When the [ver reply text] command is used, a detailed reply is returned, which can be used for troubleshooting. Below is a list of different types of replies and their meanings:

Reply Meaning Solution

This shop is not allowed to use the given currency

MerchantID is missing, or has not been registered for the currency in question.

Contact DIBS customer support

Verification denied

The transaction has been denied

Try another card, or check the funds are available on the account

This was a test

Test running

Conclude the rest run, i.e. use outside of the DIBS Manager Test Purchase feature.

During test running in DIBS Manager, the reply page always contains a comment hidden in the HTML code, containing a string with all submitted values, which is good to use during troubleshooting. For example:

<!-- ret pageSet="testPageSet" 6: {expM=01, ready=OK, billingCountry=Great Britain, billingAddress=1 Road Street, billingLastName=Smith, billingZipCode=012 34, data=1:Lollipop:2:35:, currency=GBP, cc=123, billingCity=Newcastle, method=, eMail=jsmith@xyz.co.uk, expY=01, billingFirstName=John} --> 

Do you have a 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