suppl_auth.cgi
(supplementary authorisation of a card transaction)
Note! suppl_auth.cgi is only valid for Dankort and Visa-Dankort transactions (Danish cards).
Description
suppl_auth.cgi is used to perform a supplementary authorisation of a null-authorised card transaction (see auth.cgi), as a first step of completion of a transaction capture (see capture.cgi). Essentially, the use of this function is equivalent to using the "confirm" link, which you will find for null-authorised transactions under "Payments | New / pending" in the DIBS Administration.
For compatibility reasons null-authorised transactions can be processed with capture.cgi without calling suppl_auth.cgi first, since capture.cgi will attempt an implicit supplementary authorisation first. However, it is recommended to use suppl_auth.cgi for explicit supplementary authorisation.
This function can only be successfully applied once to any transaction, and only on null-authorised transactions (i.e. payments which adhere to the three-stage model).
Function call
https://login:password@payment.architrade.com/cgi-adm/suppl_auth.cgi
Input parameters
suppl_auth.cgi accepts the following parameters:
Parameter | Description |
merchant | This is the merchant number of the shop also used during authorisation (auth.cgi). |
amount | Amount to be transferred. The amount must be given in the smallest possible unit, e.g., cents 100 = USD 1. This amount will typically be identical with one specified during authorisation, but it may be smaller, e.g. if only a subset of the order is shipped. In cases where the amount tops the amount approved by the customer, the increase must not exceed the percentage limit agreed with the acquirer (which is registered at DIBS in the acquirer agreements), and in addition, the increase must not exceed 1.000,00 DKK. |
transact | The transaction number received from DIBS when the authorisation was approved. |
textreply | When this parameter is set (e.g. textreply=true) the DIBS system 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 from DIBS. You may use either port 80 or port 20080. |
[md5key] | This parameter works as a measure against modifying the data sent to auth.cgi during "transport". The md5key parameter is a checksum based on the data sent to suppl_auth.cgi. MD5(key2 + MD5(key1 + "merchant=<mercid>&orderid=<orderid> &transact=<trans>&amount=<amt>")) The keys used for this calculation are found the DIBS Administration. Please note: The md5key parameter is only controlled if this has been enabled in DIBS Administration. |
[orderid] | This is the order number used during the acquisition of authorisation. It is only used if md5key has be calculated. |
[test] | This parameter is used while testing the shop (e.g. test=yes). When using this parameter no transactions are sent to the acquirer - they are treated in the DIBS test module. Please refer to step 5 in the 10 step guide for further information. You may want to perform more testing at a later time. In that case, DIBS has to put your shop in testing mode again (please contact support). |
[account] | If several departments of a company share the company's acquirer agreement with PBS, it is usually most practical to keep the transactions separated in DIBS. This parameter is used for specifying an "account number", which allows the transactions to be distinguishable per department. (Read more about accounts on dibs.dk, or dibs.no) |
Return value
Parameter | Description |
status | ACCEPTED/DECLINED. Specifies the result of attempting to perform a supplementary authorisation. |
Accepted supplementary authorisations furthermore return:
Parameter | Description |
transact | The transaction number allocated by DIBS (numeric, minimum 9 digits, e.g. transact=987654321). |
cardtype | The card type used (see list of available card types). |
Declined supplementary authorisations furthermore return:
Parameter | Description |
reason | Contains the reason for why a suppl_auth.cgi request was declined. See list of error codes for possible reasons. |
Example
<form action="https://login:password @ payment.architrade.com/cgi-adm/suppl_auth.cgi" method="post">
<input type="hidden" name="merchant" value="1234567" />
<input type="hidden" name="amount" value="2000" />
<input type="hidden" name="transact" value="12345678" />
<input type="hidden" name="textreply" value="yes" />
<input type="hidden" name="md5key" value="cfcd208495d565ef66e7dff9f98764da" />
<input type="hidden" name="orderid" value="11223344" />
</form>
Security
In order to keep others from altering null-authorised transactions (such as changing the amount), suppl_auth.cgi requires a user name and password. See the above example. The user name and password are identical to the ones used for accessing DIBS Administration, or the ones pertaining to the special API user type, which can created in the administration.
