3dsecure.cgi

(Authorisation of a card transaction with 3Dsecure)

Please note, that none of our components are currently working with 3Dsecure.

Description

3dsecure.cgi is used when a 3Dsecure authorisation should be performed. The 3Dsecure authorisation is performed easily by posting the cardholder (customer) to the 3dsecure.cgi script. The card number will be checked against Visa or Mastercard, and if the card number is enrolled in the 3Dsecure program, the customer will be redirected to the customer's card issuer's page to perform the authentication process. If the card number not is enrolled, an authorisation will be performed directly.

NB! Do not send other than VISA and Mastercard transactions to 3dsecure.cgi.

When the authorisation is done the customer will be sent back to either accepturl or declineurl. If the authorisation is a success the customer will be sent to accepturl and if it is denied the customer will be sent to the declineurl.

DIBS adds the parameters on the url as: transact=xxx where xxx is the transaction number. Furthermore DIBS can also add more parameters that can be set in the DIBS-administration.

Function call

https://payment.architrade.com/cgi-ssl/3dsecure.cgi

Input parameters

3dsecure.cgi accepts the following parameters:

Parameter	Description
merchant	Shop identification. The Merchant number appears in the e-mail received from DIBS during registration with DIBS or on your contract. Your merchant number can also be retreived by contacting your respective DIBS support department below. Denmark Norway Sweden
amount	The smallest unit of an amount, eg. cent for EUR , øre for Danish crowns, Example: 1,00 EUR = 100 or 1,50 EUR =150
accepturl	The URL of the page to be displayed if the purchase is approved.
cancelurl	The same as declineurl
orderId	The shop’s order number for this particular puchase. It can be seen later when payment is captured, and will in some instances appear on the customer’s bank statement (both numerals and letters may be used).
expyear	Card expiry year in two digits, 06 for 2006.
expmon	Card expiry month in two digits, 01 for january.
declineurl	The URL of the page to be displayed if the purchase is denied.
currency	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.
cardno	Card number with no spacing.
[uniqueoid]	If this field exists, the orderid-field must be unique, i.e. there is no existing transaction with DIBS with the same order number. If such a transaction already exists, payment will be rejected with reason=7. Unless you are unable to generate unique order numbers, we strongly urge you to utilize this field.Note: Order numbers can be composed of a maximum of 50 characters (DIBS automatically removes surplus characters) and that uniqueoid is therefore unable to work as intended if order numbers consisting of more than 50 characters are used.
[textreply]	If this variable is set (e.g. textreply=true) the DIBS server returns its answer in simple text format. If you are not using the standard DIBS payment window, e.g. using server-to-server requests, this significantly simplifies parsing the answer and is recommended.
[test]	This field is used when tests are being conducted on the shop (e.g. test=yes). When this field is declared, the transaction is not dispatched to the card issuer, but is instead handled by the DIBS test module. See also Step 5 of the 10 Step Guide for more information. Should the test system be used at a later date, this will be activated at DIBS (contact DIBS support for reactivating the test mode of your shop).
[priceinfo1.. priceinfoN]	Complex order information. If both complex and simple order information is declared, the simple order information is ignored. This information is displayed in the Dibs administration interface.
[preauth]	When preauth=true is sent as part of the request to auth.cgi the DIBS server identifies the authorisation as a ticket authorisation rather than a normal transaction. Please note that the pre-authorised transaction is NOT available among the transactions in the DIBS administration interface. When using MD5 the Authkey must be calculated from the string transact=12345678&preauth=true&currency=123
[ordline0-1.. ordlineN-M]	Complex order information, see Order information at DIBS. If both complex and simple order information [ordertext] is declared, the simple order information is ignored. This information is displayed in the Dibs administration interface. It is a requirement that the number of fields be identical in all lines of the order (eg. if there are four fields in the first line, the remaining lines must also contain four fields).
[ordertext]	Simple order information sent to DIBS in one text string. This information is displayed in the Dibs administration interface.
[md5key]	This variable enables a MD5 key control of the values received by DIBS. This control confirms that the values sent to DIBS has not been tampered with during the transfer. The MD5 key is calculated as: MD5(key2 + MD5(key1 + "merchant=<merchant>&orderid=<orderid>&currency= <currency>&amount= <amount>")) Where key1 and key2 are shop specific keys available through the DIBS administration interface, and + is the concatenation operator. NB! MD5 key check must also be enabled through the DIBS administration interface in order to work. Further details on MD5-key control.
[ip]	DIBS retains the IP-number from which a card transaction is carried out. The IP-number is used for ’fraud control’, etc. Some implementations may send the IP number of the shop to DIBS rather than that of the customer's machine. In order to provide the same services to shops which utilize such a program for their DIBS hookup, we offer the option of sending the “ip” parameter.
[fullreply]	If this variable is set, all variables will be returned (as defined in the DIBS admin). Note: This only works when used together with textreply.
[delivery1..deliveryN]	Complex order information. If both simple and complex order information (ordertext) is declared, the simple order information is then ignored. This information is stored in the DIBS administration interface. Note: That the following parameter is mandatory when using the polish wire transfer service Przelewy24. "delivery1.Email" Example: <input type="hidden" name="delivery1.Email" value="my@email.com"/>
[cvc]	Card control values.
[capturenow]	If this field exists, an "instant capture" is carried out, i.e. the amount is immediately transferred from the customer’s account to the shop’s account. This function can only be utilized in the event that there is no actual physical delivery of any items. Contact DIBS when using this function. (Note that instant capture requires unique order numbers – also see the description of uniqueoid above).
[callbackurl]	An optional ”server-to-server” call which tells the shop’s server that payment was a success. Can be used for many purposes, the most important of these being the ability to register the order in your own system without depending on the customer’s browser hitting a specific page of the shop. See also HTTP_COOKIE.
[account]	If multiple departments utilize the company’s acquirer agreement with the acquirer, it may prove practical to keep the transactions separate at DIBS. An ”account number” may be inserted in this field, so as to separate transactions at DIBS.
[HTTP_COOKIE]	Cookies/sessions which are to be sent to callbackurl. Must be sent along if you are using callbackurl and depend on cookies/sessions for keeping track of the user.

Return pages

The customer returns to ”accepturl” once payment is approved
The customer returns to ”declineurl” once payment is denied

Payment approved (accepturl)

Upon returning to accepturl, the customer will normally expect a receipt to be displayed. We therefore recommend you use the accepturl option for generating a customer receipt.

The following parameters return the user to the accepturl:

Parameter	Description
transact	The unique DIBS identification number for the transaction you want to capture. The transact is returned from a successful authorisation, and is a as minimum 6-digit integer , e.g. transact=123456.
[paytype]	The type of payment the customer has used for a particular payment. The payment type is returned as a string. Paytype is only returned if a member of the DIBS administration has activated a return of all values (under installation + return values).
[acquirer]	The acquirer used for the specific transaction. See also our list of valid values for acquirer.
[authkey]	The MD5 check sum for verification of the authenticity of the transaction. This is only returned if an MD5 key is created within the administration (under installation + MD5 keys). You may read more about MD5 key control. *Note:* When using a payment window and the calcfee function, amount+fee is used as a basis for calculations rather the amount only.
[suspect]	Is returned if there is a subscription to fraud control and this is activated in the administration interface (in such a case, this may have the value ”true”).
[fee]	When calcfee is used, the calculated fee is returned so it can be shown on the receipt.
[severity]	Whole numbers. Is returned if fraud control has noted the transaction as a potential fraud, if there is a subscription to fraud control and if this is activated in the administration interface. The higher the amount, the more questionable the transaction. We generally recommend closer checks of transactions with severity > 5.
[merchant, amount...]	All parameters sent to start.pml are returned to accepturl.
[?X=4&Y=2...]	All cgi-parameters included with the accepturl via POST – this also applies to cancelurl. Reserved words cannot be used as declared cgi-parameters (see list of reserved words at bottom of page). If several parameters are declared via DIBS, it should be noted that browsers use various maximum lengths of query-strings (eg. 2083 characters for IE).

Payment denied (declineurl)

"cancelurl" indicated:

CGI-parameters sent to the declineurl are also returned (?x=1&y=4). Note: Reserved words cannot be used as declared cgi-parameters (see list of reserved words at bottom of page).

Automatic call-back (callbackurl)

There is a potential risk of the customer not following the link to the receipt and subsequently never seeing one. If the shop system is set up so that orders are stored in the database at the same time the receipt is displayed to the customer, the order may in fact escape registration within the shop’s own system. This would be rather unfortunate since payment is authorized with DIBS, the customer believes DIBS has authorized the payment, and the customer believes that the order has been carried out, yet the shop’s system has no knowledge of any such order.

To avoid such an occurrence, DIBS automatically enables the approved page to call a script in the shop’s system without involving the customer in the procedure. As is the case with the receipt page, this script must inform the shop’s order system that the order has been carried out and send an order confirmation to the customer, if so required. It can also serve as an MD5 key control to ensure that the customer himself does not call the script, resulting in the shop interpreting the order status as “carried out”.

In order to activate the automatic call-back a callback-url must be declared to the payment window. This is done through the callbackurl parameter. The url shown is then automatically called when the approved-page is displayed. The call is created as a post and all parameters are sent to start.pml, cgi-parameters sent along to callbackurl (?x=1&y=4) and transaktionsid and the MD5-encryption key can be sent along (the same parameters that are returned via accepturl are always along). Note: Reserved words cannot be used as declared cgi-parameters (see list of reserved words at bottom of page).

If the call-back script is dependent on cookies or sessionid, these must also be sent along to the payment window in the "http_cookie" parameter. The value of this variable must contain the form: name1=value1; name2=value2...

If you should wish to transfer all declared cookies, the content of the HTTP_COOKIE variable can be used, this containing all the cookies in the correct format.

Below are a few examples of how to do this in ASP, PHP4 and JavaScript:

Reserved words

The following variables must not be used in the call (POST) to the payment window, since these are already used internally within the window:

status, step, rid, paytype, authkey, transact, cardtype, expmon, expyear, cardno, cvc, phoneno, fee, modulook

Parameters which are sent to the payment window must not be used as declared cgi-parameters at accepturl, cancelurl and callbackurl. The same applies to the following parameters which are automatically returned to accepturl, cancelurl and callbackurl:

merchant, amount, currency, orderid, accepturl, opener, test, cancelurl, callbackurl, http_cookie, lang, calcfee, ordertext, delivery1..deliveryN, ordline0-1..ordlineN-M, priceinfo1..priceinfoN, transact, authkey, suspect, fee, severity

Important notes

* Parameters indicated with [parameter] are optional.

* Parameters without [ ] are mandatory

Example