auth.cgi

The function auth.cgi performs the first part of a credit card transaction (the authorization). The authorization includes e.g. credit- and debit-card control and reservation of the required amount for later capture. auth.cgi can be used from a standard HTML form embedded in the website (web shop) using the DIBS payment window, but may also be called directly from one's own script. The latter requires a valid SSL certificate.

Function call

https://payment.architrade.com/cgi-ssl/auth.cgi
Permission to send card data must be activated by DIBS. Usage of auth.cgi requires a PCI certification. If you are creating payments through the API auth.cgi you need to ensure that you have the right PCI-certificate to do so.

Example

Below is an example of a payment authorized using the recommended parameters for auth.cgi.

<form method="post" action="https://payment.architrade.com/cgi-ssl/auth.cgi">
    <input type="hidden" name="merchant" value="98765432">
    <input type="hidden" name="amount" value="2000">
    <input type="hidden" name="currency" value="208">
    <input type="hidden" name="cardno" value="5019100000000000">
    <input type="hidden" name="cvc" value="123">
    <input type="hidden" name="md5key" value="cfcd208495d565ef66e7dff9f98764da">
    <input type="hidden" name="expmon" value="12">
    <input type="hidden" name="expyear" value="05">
    <input type="hidden" name="orderid" value="11223344">
</form >

Essential input parameters

 ParameterDescription
amount *

The smallest unit of an amount in the selected currency, following ISO4217 (see the minor unit list here).

Example:

Smallest unit for EUR is "cent" thus setting 'amount="150"' leads to the amount being 1,50 EUR
Smallest unit for JPY is "yen" thus setting 'amount="150"' leads to the amount being 150 JPY
cardno *

Returns the full card number where all but the last 4 digits are masked.

currency *

Currency is defined using the ISO4217 standard (see the currency list here). Both numeric and upper case letter codes are accepted.
Example:

currency="SEK"
currency="752"
cvc **

Card Verification Code.

expmon *

Card expiry month in one or two digits, e.g. 01 or 1 for january.

expyear *

Card expiry year in one or two digits, e.g. 06 or 6 for 2006.

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.

md5key

This variable enables an 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. See how MD5 is calculated here

Note: When using MD5, the order id must be unique.

merchant *

Shop identification. The Merchant number appears in the e-mail received from DIBS during registration with DIBS or on your contract.

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).
textreply *

Should be declared to receive the returned message in simple text format.

* : Mandatory parameters

** : Almost all acquires/card issuers require this to be used but is optional through DIBS if it's deactivated in the administration.

Optional input parameters

Parameter Description
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.

account

If multiple departments utilize the same DIBS account, it may be practical to keep the transactions separate at DIBS. An account name may be inserted in this field, to separate transactions at DIBS.

To get an account, please contact the DIBS sales department.

acquirerinfo The information added here will appear on the card holders bank statement for Handelsbanken transactions. (Cekab/Evry)
calcfee

If this parameter is sent with the value "yes", the charge from the acquirer due to the transaction will automatically be calculated and affixed.

Fee calculation method: Fee = Amount * Percent / (100-Percent)

NOTE: To use this parameter you need to contact DIBS Support with the fees you have at your acquirer, as they need to be entered into our system.

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.

You cannot use parameters in the url, e.g. ”?X=4&Y=2”. The URL’s have to be ”clean”.

capturenow

If this field exists, a capture request is automatically carried out after the authorization, following the normal capture process of the specific acquirer.

If a transaction is marked as suspect, the automatic capture request is cancelled and you need to handle the capture.

If used, the order id has to be unique at all times.

cardtype

Returns the type of payment the customer has used for a particular payment.

confirm

This parameter is used for enforcing either the two-stage or the three-stage model. Possible values are:

now = enforce two-stage model.

later = enforce three-stage model (if allowed).

You are always allowed to enforce the two-stage model. However, the three-stage model has the following restrictions:

- The purchase must be done with a Dankort

- The function must be activated by the DIBS support

- Capturenow cannot be used, as it enforces the full amount to be authorized instantly.

ip

DIBS retains the IP-address from which a card transaction is carried out. The IP-address is used for ’fraud control’, etc. Some implementations may send the IP address 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.

notifyurl

Some acquirers might take a period of time before the payment is accepted. This parameter can be used to specify a callback URL to get a response at a later time when the transaction is either accepted or declined. 

postype

Used to register the transaction origin. Default value is "ssl" (internet). Following values are possible:

ssl = internet transactions,

magnetic = magnetic stripe read, and signature is available,

magnosig = magnetic stripe read, and no signature is available,

mail = mail order,

manual = manually entered,

phone = phone order,

signature = card and signature available, manually entered.

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.
For preauth to work, DIBS has to be contacted for activation.
When using preauth and MD5 checks, the md5key parameter in the request is not checked. The authkey in the response must be calculated from the string transact=12345678&preauth=true&currency=123. 
NOTE: You cannot use "capturenow" along with "preauth".
return_checksum

If "return_checksum" is sent to the DIBS server, a checksum of the card number will be returned in the 'checksum' parameter. This checksum will always be card-unique, and can therefore be used to check if the specific card has been used in a previous purchase in the shop.

test

When this field is declared, the transaction is not dispatched to the card issuer, but is instead handled by the DIBS test environment. When the shop goes live, the test system is normally disabled, and should the shop want to use the test mode at a later date the DIBS support can be contacted for reactivation.

uniqueoid

If this parameter is present, the parameter orderid has to be unique compared to all other orderid's used by the merchant.
If the orderid isn't unique, the call will be declined by a reason=7.
Note: Order numbers can be composed of a maximum of 50 characters (DIBS automatically removes surplus characters).

 

Return parameters

Payment accepted

When the payment is accepted, the following parameters are always returned:

Parameter Description

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 parameter, amount+fee is used as a basis for calculations rather the amount only.

approvalcode

Returns the approvalcode from the acquirer if available.

status

ACCEPTED/DECLINED

transact

The unique DIBS identification number for the transaction.

The following parameters are returned if the parameter "fullreply" is sent and the return values is activated in DIBS admin:

Integration / Return Values

DIBS recommend that all Return Values are activated.

Parameter Description
?X=4&Y=2...

All custom parameters defined by the shop, is returned. Reserved words cannot be used as custom parameters.

If several parameters are declared, it should be noted that browsers use various maximum lengths of query-strings (eg. 2083 characters for IE).

acquirer

Returns the acquirer used for the specific transaction.

cardcountry

Returns the nationality of the card in "ISO 3166-1 alpha-2" standard

cardexpdate

Returns the expiry date of the card in the fomat "yymm"

cardnomask

Returns the full card number where all but the last 4 digits are masked.

cardprefix

Returns the 6-digit prefix of the card used in the transaction.

cardtype

Returns the type of payment the customer has used for a particular payment.

merchant, amount...

All parameters sent in the call are returned in the response.

merchantid

Returns the acquirer agreement ID.

paytype

Returns cardtype(short) for card transactions and acquirer(short) for other payments

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”).

Activated in DIBS admin in:

Integration / Fraud Protection

 

Return parameters

Payment declined

If the payment is declined the following parameters are returned: 

ParameterTypeDescription

status

string

ACCEPTED/DECLINED

reason

integer

Returns a reason for the rejection.

The following parameters are returned if the parameter "fullreply" is sent and the return values is activated in DIBS admin:

Integration / Return Values

DIBS recommend that all Return Values are activated.

ParameterDescription
?X=4&Y=2...

All custom parameters defined by the shop, is returned. Reserved words cannot be used as custom parameters.

If several parameters are declared, it should be noted that browsers use various maximum lengths of query-strings (eg. 2083 characters for IE).

merchant, amount...

All parameters sent in the call are returned.

 

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