3d-Secure guide

The DIBS Server Solution offers funcionality for sending transactions using 3-D Secure.

First of all a word of notice: Please observe that 3-D Secure transactions must be authorized using the authorize3DS or authorizeAndSettle3DS methods. Transactions authorized using the regular authorize/authorizeAndSettle methods can never be 3-D Secure transactions.

Please note that 3-D Secure is currently available for payment methods cc.babs, cc.cekab, cc.euroline, cc.invik, cc.luottokunta and cc.valitor.

Flow Description

The process consists of two major steps: The first step is the enrollment query step, where the merchant asks DIBS if the credit card is enrolled in the 3-D Secure program. The second step involves completing the 3-D Secure authentication and calling DIBS's authorize3DS or authorizeAndSettle3DS functions.

Enrollment Query

The merchant calls the askIf3DSEnrolled method in the Server Solution with the same parameters as for the authorize method, plus the HTTP Accept and User Agent headers from the end user's browser (needed for creation of authentication request).
DIBS checks the enrollment status of the card. If the card number is in an interval that is enrolled in 3-D Secure, a Payment Authentication Request (PaReq) is created and the enrolled status is returned. If not, the card is considered not enrolled and no further authentication is necessary.
The DIBS server response back to the client will contain the following elements:

	Response Code	VerifyID	ACS URL	PaReq Value
If enrolled:	107	Present	Present	Present
If not enrolled:	108	Present	Not Present	Not Present
If unable to authenticate:	207	Present	Not Present	Not Present
If not Visa or MasterCard:	322	Not Present	Not Present	Not Present

If the enrollment response from DIBS is 107 (enrolled), then the merchant must send the consumer to the Issuing Bank URL specified in the ACS_URL part of the DIBS Server response (ACS – Access Control Server). In addition to this, the PaReq value must be included in the request to the ACS URL.
If the response is 108 (not enrolled), then the merchant can go ahead with a 3-D Secure enabled authorization and settlement.
When the response is 207, the credit card may not be used for 3-D Secure processing at this time. There can be several reasons for this, including technical problems at the issuing bank. This means that the merchant cannot claim a liability shift for this card, which means that if the merchant really wants to use the card, it must be used without 3-D Secure. The recommended action to take is to seek a different form of payment, for example a different card.
Response code 322 means that the card sent in was neither a Visa nor a MasterCard credit card. Such a credit card can not be used in a 3-D Secure payment, so the merchant must switch to using the regular authorize or authorizeAndSettle methods.

Scenario 1: Enrolled Card, Full 3-D Secure Authentication

When the enrollment response is 107 (enrolled), the merchant must send the consumer to the bank that has issued his/her card. The URL to send the consumer to (the ACS URL) is included in the enrollment response from the Server Solution.
The request that the consumer's browser makes to the ACS URL must contain the following parameters:

PaReq – the PaReq message from the DIBS server response.
TermUrl – the URL (at the merchant's web site) that the authenticating bank should send the consumer back to upon completion of the authentication.
MD (Merchant Data) – the reference number for the transaction. This parameter will be included in the request to the TermUrl so that the merchant will be able to identify the transaction.

The suggested procedure is to return a page that uses a JavaScript function to
post a form to the ACS_URL:

<html>
 <body OnLoad='OnLoadEvent();'>
  <form name=downloadForm action= "ACS_URL" method="POST">
   <input type=hidden name=PaReq value="PaReq">
   <input type=hidden name=TermUrl value="TermUrl">
   <input type=hidden name=MD value="MD">
  </form>
  <script language=Javascript>
   document.downloadForm.submit();
  </script>
 </body>
</html>

The reason that the JavaScript posting method is preferred is that a normal redirect causes the browser to use GET instead of POST. Visa requires that this request be done as a POST.

Handling the Authentication Response

The consumer returns from the authentication to the TermUrl that was included in the form. When the consumer returns, two parameters will be included: MD and PaRes.

MD contains the same reference number sent in the MD parameter to the ACS URL. Should be used to look up the correct transaction in the merchant's system.
PaRes contains the Payment Authentication Response that must be sent in to DIBS in the next method call.

authorize3DS / authorizeAndSettle3DS

To complete the authentication and authorize the payment, the PaRes value must be sent in to DIBS using the authorize3DS or the authorizeAndSettle3DS methods. The parameters are:

verifyID – the verifyID of the transaction that was sent back in the response to the askIf3DSEnrolled call.
PaRes – the PaRes value received from the issuing bank.

There are a few new possible responses from the DIBS server:

	Response Code	VerifyID
If authentication not ok:	209	Present
If authentication timed out:	318	Present
If no record of authentication exists at DIBS:	320	Present

The 318 (pares_too_late) will be used when the authenticate3DS call comes later than a certain amount of time. This is presently set to 15 minutes, but may be subject to change in the future.
When the authentication is ok, the response codes will the same as they do for regular calls to authorize and authorizeAndSettle.

Scenario 2: Not Enrolled, No More 3DS Necessary
When the enrollment response is 108 (not enrolled), then no more 3-D Secure processing needs to take place. The merchant can go ahead and call the authorize3DS or authorizeAndSettle3DS methods directly. The parameters to use
are of course the same as for scenario 1:

verifyID – the verifyID of the transaction that was sent back from DIBS in the response to the askIf3DSEnrolled method call.
PaRes – in this case this parameter should be sent in empty.

The response codes are the same as for scenario 1.

Scenario 3: Neither Visa nor MasterCard
The enrollment response 322 (neither visa nor MasterCard) means that the merchant has sent in a credit card number is neither Visa nor MasterCard. These cards must be authorized and settled without 3-D Secure, i.e. the merchant must switch to using the non-3-D Secure authorize or authorizeAndSettle methods.

Flow Chart
The following flow chart describes the procedure to follow when using the 3-D Secure functionality of the DIBS Server Solution.

MAC for 3-D Secure calls

All calls made to DIBS may use the message authentication code to increase security. See 4.5 Message Authentication for more information regarding MAC. The MAC formula to use for the different calls can be found below. See the three available formulas on page 12.

Call	Formula
askIf3DSEnrolled	3- X('data&currency&[referenceData&]SecretKey&')
authorize3ds	1- X('VerifyId&SecretKey&')
authorizeAndSettle3DS	1- X('VerifyId&SecretKey&')

As always, the MAC parameter is included into the “extra” parameter and is notuse explicitly in the server calls.

Secure Specific Response Codes

return code	return text	description
107	enrolled	The card is enrolled. The consumer should be sent to his/her issuing bank.
108	not_enrolled	The card is not enrolled. The purchase can continue with no more authentication actions.
207	unable_to_authenticate	The credit card sent in may not be used for 3-D Secure processing at this point in time. You may not claim a liability shift on this transaction under any circumstances. In this case, DIBS's recommendation is to seek a different form of payment.
209	authentication_denied	The 3-D Secure authentication was unsuccessful.
318	pares_too_late	The PaRes came in too late after the initial call to askIf3DSEnrolled.
319	authentication_not_allowed	This merchant is not configured to use 3-D Secure authentications.
320	no_preceding_authentication	An authorization without preceding authentication has been entered.
321	authentication_not_available	Indicates that no 3-D Secure authentication is available for the payment method sent in.
322	neither_visa_nor_mc	The credit card sent in is neither a Visa nor a MasterCard credit card. 3-D Secure processing is only possible for Visa and MasterCard payments. The merchant should switch to a non-3-D Secure authorization. (i.e. using authorize or authorizeAndSettle).
323	pares_empty	The PaRes was sent in empty (this error code will only be used when doing a full 3-D Secure authentication).
324	duplicated_authorization	There is already an authorization for the verifyID.