ticket_auth.cgi
Description
The DIBS payment gateway offers a facility for subscription payments/transactions, a so-called ticket transaction. In short, this means that the customer's credit card is authorised once, and the details for the credit card (the ticket) may then be used for more than one transaction on several future occasions, e.g. a monthly payment of $15 to cover your cell-phone bill. This allows the customer to continuously pay for goods or services without having to send his/her credit card details again and again.
The credit card details are stored on the DIBS server in accordance with the strict rules of VISA/Mastercard. Tickets for which the credit card has expired are also considered expired, and the customer has to make a new ticket with another card to re-establish his/her subscription payment.
3-D Secure
Recurring payments can be forced through 3D Secure, which validates the credit card details against the card issuer's system. This feature is enabled on a per-agreement basis, i.e., per card issuer. To activate this feature please contact DIBS Support.
Usage
The standard work flow for ticket_auth.cgi is:
- The credit card details are submitted to the DIBS server for a so-called pre-authorisation by sending the "preauth" parameter either to auth.cgi or to Flexwin.
- The response from the pre-authorisation is returned along with a ticket number.
Once you require to make a ticket transaction, the actual transaction must be authorised using the ticket and the order information by calling https://payment.architrade.com/cgi-ssl/ticket_auth.cgi. - The result of the authorisation of the transaction is then returned along with a transaction number.
- To capture the ticket payment, use either the standard procedure of the DIBS administration interface or use the function capture.cgi.
- In order to delete a pre-authorised ticket use the function delticket.cgi.
Function call
https://payment.architrade.com/cgi-ssl/ticket_auth.cgi
Input parameters
The input parameters accepted by ticket_auth.cgi for the actual transaction authorisation are:
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 |
| 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). |
| ticket | The ticket number, which is identical to the transact returned from the DIBS server from the accepted pre-authorisation process. |
| textreply | If this variable is set to be true (e.g. textreply=yes), then 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. |
| 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. |
| [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. |
| [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. |
| [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). |
| [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>
&ticket=<ticket>¤cy=<cur>&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 displayed to the customer in the payment window and is stored at DIBS. |
| [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). |
| [calcfee] | If this parameter is set (e.g. calcfee=foo), the charge due to the transaction will automatically be calculated and affixed, i.e., the charge payable to the acquirer (e.g. PBS) |
| [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. |
Return parameters
The return parameters from ticket_auth.cgi when the ticket authorisation was accepted are:
Parameter | Type | Description |
| transact | integer | All transactions are given a unique DIBS identification number. It is at minimum a 6-digit integer, e.g. transact=123456. If "split" is used, then "transact" is replaced by "transact1", "transact2", etc. |
| status | string | ACCEPTED/DECLINED |
| cardtype | string | Credit card type used |
| approvalcode | string. max 32 characters | The acquirer authorisation code |
| [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.
| |
| [fee] | integer | When calcfee is used, the calculated fee is returned so it can be shown on the receipt. |
If the pre-authorisation was rejected, then the return values are:
Parameter | Type | Description |
| status | string | ACCEPTED/DECLINED |
| reason | integer | If the transaction is rejected, it returns with a reason for the rejection. Please refer to error codes for a list of possible values. |
Example
This example shows a standard HTML form for calling ticket_auth.cgi for an authorisation of a ticket transaction.
<form action="https://payment.architrade.com/cgi-ssl/ticket_auth.cgi" method="post">
<input type="hidden" name="merchant" value="4206891" />
<input type="hidden" name="ticket" value="270000543" />
<input type="hidden" name="amount" value="1000000" />
<input type="hidden" name="currency" value="208" />
<input type="hidden" name="orderid" value="A Ticket Draw" />
<input type="hidden" name="textreply" value="true" />
<input type="hidden" name="test" value="yes" />
<input type="hidden" name="calcfee" value="yes" />
<input type="hidden" name="md5key" value="264f0737cff3be64d3050a8141568266">
<input type="submit" value="Click to call ticket_auth.cgi" />
</form>
Submitting this form returned the following:
status=ACCEPTED&transact=270001151&authkey=df9a8e577299394ab7e5e7f538699652&cardtype=VISA&approvalcode=123456&fee=61008
Calculation of the 'md5key' input to DIBS:
The shops secret keys are:
k1: D*OU+kG^O!r5Bo#oc}k$H^~ow-P6:WX:
k2: U:s0;gq|$|1sS8r(lYJKc~?[iXWf?SVP
MD5(k2 + MD5(k1 + "merchant=<merchant>&orderid=<orderid>&ticket=<ticket>¤cy=<cur>&amount=<amount>")) =
MD5(k2 + MD5(D*OU+kG^O!r5Bo#oc}k$H^~ow-P6:WX: + "merchant=4206891&orderid=A Ticket Draw&ticket=270000543¤cy=208&amount=1000000")) =
MD5(k2 + MD5(D*OU+kG^O!r5Bo#oc}k$H^~ow-P6:WX:merchant=4206891&orderid=A Ticket Draw&ticket=270000543¤cy=208&amount=1000000)) =
MD5(k2 + dd6244e9aaed0fab3b9fa1ff7360c7f9) =
MD5(U:s0;gq|$|1sS8r(lYJKc~?[iXWf?SVP + dd6244e9aaed0fab3b9fa1ff7360c7f9) =
MD5(U:s0;gq|$|1sS8r(lYJKc~?[iXWf?SVPdd6244e9aaed0fab3b9fa1ff7360c7f9) =
md5key=264f0737cff3be64d3050a8141568266
Calculation of the 'authkey' returned from DIBS:
(The shops secret keys are as above)
MD5(k2 + MD5(k1 + "transact=<transact>&amount=<amount>¤cy=<currency>")) =
MD5(k2 + MD5(k1 + "transact=270001151&amount=1000000 + 61008¤cy=208")) =
MD5(k2 + MD5(D*OU+kG^O!r5Bo#oc}k$H^~ow-P6:WX: + "transact=270001151&amount=1061008¤cy=208")) =
MD5(k2 + MD5(D*OU+kG^O!r5Bo#oc}k$H^~ow-P6:WX:transact=270001151&amount=1061008¤cy=208)) =
MD5(U:s0;gq|$|1sS8r(lYJKc~?[iXWf?SVP + 29e35d3584be0ace99528a653867b3fb) =
MD5(U:s0;gq|$|1sS8r(lYJKc~?[iXWf?SVP29e35d3584be0ace99528a653867b3fb) = authkey=df9a8e577299394ab7e5e7f538699652