Introduction
The 3D Secure authentication request is used when the initial transaction has been returned as requiring the customer to validate their card details with their card issuer. This validation interrupts the payment process & effectively causes a single transaction to be handled in 2 distinct messages – the first message is the initial CardDetailsTransaction message, which completes with a “3D Secure validation required” result & the second message, which contains the 3D Secure validation response from the customer’s card issuer (collected by the customer themselves). The ThreeDSecureAuthentication is the second of the two messages described above.
Request
Below are the details for the request message to initiate a 3D Secure authentication transaction.
|
Tag/Attribute Name |
Data Type |
Max Length |
Mandatory |
Comments |
||
|
ThreeDSecureMessage |
Yes |
|
||||
|
|
MerchantAuthentication |
Yes |
|
|||
|
|
MerchantID |
A |
15 |
Yes |
The gateway account merchant ID issued (not to be confused with the MMS username) |
|
|
|
Password |
A |
15 |
Yes |
The gateway account password |
|
|
|
ThreeDSecureInputData |
Yes |
|
|||
|
|
CrossReference (attribute) |
A |
25 |
Yes |
The cross reference returned by the previous response that included the ThreeDSecureOutputData |
|
|
|
PaRES |
A |
– |
Yes |
The base64 encoded PaRES string returned by the interaction with the ACS server |
|
Response
Below are the details for the response that will be received after sending a ThreeDSecureAuthentication request.
|
Tag/Attribute Name |
Data Type |
Max Length |
Always Present |
Comments |
||||
|
ThreeDSecureAuthenticationResponse |
Yes |
|
||||||
|
|
ThreeDSecureAuthenticationResult |
Yes |
|
|||||
|
|
AuthorisationAttempted (attribute) |
B |
– |
Yes |
This indicates whether the transaction was actually sent to the acquirer for authorisation, or whether it failed before authorisation |
|||
|
|
StatusCode |
N |
– |
Yes |
This indicates the status of the transaction |
|||
|
|
Message |
A |
– |
Yes |
This gives a more detailed descriptionofthestatusof the transaction |
|||
|
|
ErrorMessages |
No |
|
|||||
|
|
|
MessageDetail |
Yes |
|
||||
|
|
Detail (multiple) |
A |
256 |
Yes |
If there were multiple error messages(e.g.multipleinput variable validation errors, then they will be detailed here) |
|||
|
|
PreviousTransactionResult |
No |
|
|||||
|
|
StatusCode |
N |
|
Yes |
If the transaction was deemed to be a duplicate transaction, this indicates the status of the previous transaction |
|||
|
|
Message |
A |
|
Yes |
If the transaction was deemed to be a duplicate transaction, this givesamore detailed description of the status of the previous transaction |
|||
|
|
TransactionOutputData |
No |
|
|||||
|
|
CrossReference (attribute) |
A |
25 |
Yes |
This is the unique cross reference for this transaction. If the transaction was rejected as a duplicate transaction, this value will hold the cross reference of the previous transaction |
|||
|
|
ExternalCrossReference (attribute) |
A |
– |
No |
If requested in the initial CardDetailsTransaction or CrossReference request message, this gives the unique cross reference of the transaction from the bank’s external system passed back to the Payment Gateway. |
|
|
ExternalClientReference (attribute) |
A |
– |
No |
If requested in the initial CardDetailsTransaction or CrossReference request message, this gives the unique client reference of the transaction from the bank’s external system passed back to the Payment Gateway. |
|
|
ExternalTransactionUID (attribute) |
A |
– |
No |
If requested in the initial CardDetailsTransaction or CrossReference request message, this gives the unique identifier of the transaction from the bank’s external system passed back to the Payment Gateway. |
|
|
AuthCode |
A |
15 |
No |
If the transaction was successful, then the auth code is passed out here |
|
|
AddressNumericCheckResult |
– |
– |
No |
If requested in the initial CardDetailsTransaction or |
|
|
|
|
|
|
CrossReferenceTransaction request message, this gives the results of the address numeric check – will be PASSED, FAILED, NOT_CHECKED or UNKNOWN |
|
|
PostCodeCheckResult |
– |
– |
No |
If requested in the initial CardDetailsTransaction or CrossReferenceTransaction request message, this gives the results of the post code check – will be PASSED, FAILED, NOT_CHECKED or UNKNOWN |
|
|
CV2CheckResult |
– |
– |
No |
If requested in the initial CardDetailsTransaction or CrossReferenceTransaction request message, this gives the results of the CV2check – will be PASSED, FAILED, NOT_CHECKED or UNKNOWN |
|
|
ThreeDSecureAuthenticationC heckResult |
– |
– |
No |
This gives the results of the 3D Secure authentication check – will be PASSED, FAILED or UNKNOWN |
||
|
|
CardTypeData |
No |
|
||||
|
|
CardType |
A |
– |
Yes |
If requested in the initial CardDetailsTransaction or CrossReferenceTransaction request message, this gives the card type for the transaction. (See Appendix 4 for details) |
||
|
|
Issuer |
A |
100 |
No |
The card issuer (if known) |
||
|
|
AmountReceived |
N |
15 |
No |
If requested in the initial CardDetailsTransaction or CrossReferenceTransaction request message, this gives the amount that was passed to the gateway via the request message |
||
|
|
GatewayEntryPoints |
Yes |
|
||||
|
|
|
GatewayEntryPoint (multiple) |
Yes |
|
|||
|
|
EntryPointURL (attribute) |
A |
256 |
Yes |
The URL of the active gateway entry point |
||
|
|
Metric (attribute) |
N |
5 |
Yes |
A metric value giving an indication of whether transactions should be sent to this gateway entry point |
||
Things to Note
-
The contents of the variable “MD” used in the 3D Secure validation process should be passed in as
the CrossReference of the ThreeDSecureAuthentication message
-
The value of the ThreeDSecureAuthentication results will give the results of the 3D Secure authentication – it will be either PASSED, FAILED or UNKNOWN. It is worth noting that in some cases, even if the authentication is UNKNOWN or FAILED, then the transaction can still be processed (albeit without the liability shift that happens with 3D Secure authentication)