3-D Secure
If your merchant account is enabled for 3-D Secure, all 'sale' or 'preauth' transactions that you initiate by posting an HTML form will by default go through the 3-D Secure process without the need for you to do anything, i.e. cardholders with an enrolled card will see a page from the card issuer to enter the password unless the card issuer decides not to check it.
After the authentication, we bring the cardholder back to your webstore. If your credit card agreement includes 3-D Secure and your Merchant ID has been activated to use this service, you do not need to modify your payment page.
Initial Request
The following table represents the overview of mandatory and optional parameters to be included in every transaction request. In some cases, the Gateway automatically submits a default value if the parameter is missing.
Please note, that for cases, where the information is only to be provided by the cardholder, the Gateway has no option to populate default or predefined values.
| Field Name | Description |
|---|---|
authenticateTransaction | Optional parameter to be set either to ‘true’ or ‘false’ to enable or disable 3-D Secure authentication on a transaction-by-transaction basis. Example for a transaction with 3-D Secure: <input type="hidden" name="authenticateTransaction" value="true"/>Example for a transaction without 3-D Secure: <input type="hidden" name="authenticateTransaction" value="false"/> |
threeDSRequestorChallengeIndicator | Optional parameter for EMV 3-D Secure v2 to indicate the preferred type of authentication: 01 = no preference (set as default value) 02 = no challenge requested 03 = challenge requested (3DS requestor preference) 04 = challenge requested (mandate) 05 = No challenge requested (Transaction Risk Analysis is already performed) 06 = No challenge requested (Data Share Only) 07 = No challenge requested (SCA is already performed) 08 = No challenge requested (Utilize whitelist exemption if no challenge required) 09 = Challenge requested (Whitelist prompt requested if challenge required) |
threeDSTransType | The parameter for EMV 3-D Secure v2, represents the type of purchased item, mandatory for Visa and Brazilian market, otherwise optional. If no specific value present in the transaction request, default value is used. 01 - Goods/ Service Purchase (default value) 03 - Check Acceptance 10 - Account Funding 11 - Quasi-Cash Transaction 28 - Prepaid Activation and Load |
scaExemptionIndicator1 | Use this optional parameter to request an exemption from Strong Customer Authentication (SCA) without the need to perform 3-D Secure authentication. Currently available values: Low Value Exemption TRA Exemption Trusted Merchant Exemption SCP Exemption Delegated Authentication Authentication Outage Exception This parameter is relevant only for the distribution channels impacted by PSD2 requirements. |
skipTRA | This optional parameter allows you to use 3-D Secure even if the transaction has been evaluated as low risk and would be eligible for an exemption. Currently available values: true false When your store has been set up with Transaction Risk Analysis (TRA) service, but you do want to force 3-D Secure authentication for a certain transaction, set ‘skipTRA’ to ‘true’. This parameter is relevant only for the distribution channels impacted by PSD2 requirements. |
oid | Use this optional parameter to assign an identifier for your order; in case you plan to authenticate the transaction using EMV 3DS protocol (aka 3DS 2.x) only the following characters are allowed: A-Z, a-z, 0-9, "-" |
bname | Customer's full name |
baddr1 | Customers Billing Address 1, alphanumeric 96 characters max, including spaces |
baddr2 | Customers Billing Address 2, alphanumeric 96 characters max, including spaces |
bcity | Billing City, 96 characters max, including spaces |
bstate | Billing State, Province or Territory (if applicable), |
bcountry | Billing address country, format: 2 or 3 characters ISO Country Code |
bzip | Billing address ZIP or postal code, alphanumeric 96 characters max, including spaces |
phone | Customer's Phone Number, 32 characters max |
email | Customer's email address |
The following represents an example of a ‘Sale’ transaction request with minimum set of elements including “Challenge Indicator” value:
<!-- #include file="ipg-util.asp"-->
<html>
<head><title>IPG Connect Sample for ASP</title></head>
<body>
<p><h1>Order Form</h1></p>
<form method="post" action=" https://test.ipg-online.com/connect/gateway/processing ">
<input type="hidden" name="txntype" value="sale">
<input type="hidden" name="checkoutoption" value="combinedpage">
<input type="hidden" name="timezone" value="Europe/Berlin"/>
<input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
<input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
<input type="hidden" name="hashExtended" value="<% call createExtendedHash( "13.00","978" ) %>"/>
<input type="hidden" name="storename" value="110995000" />
<input type="hidden" name="mode" value="payonly"/>
<input type="hidden" name="paymentMethod" value="V"/>
<input type="text" name="chargetotal" value="13.00" />
<input type="hidden" name="currency" value="978"/>
<input type="hidden" name="authenticateTransaction" value="true"/>
<input type="text" name="threeDSRequestorChallengeIndicator" value=”1”/>
<input type="submit" value="Submit">
</form>
</body>
</html>
NOTE
In case you submitted 'OrderId' element in your request, please make sure to include only allowed characters: A-Z, a-z, 0-9, "-", please do not use special characters or spaces
The result of the transaction will be sent back to the defined responseSuccessURL or responseFailURL as hidden fields:
{txndate_processed=20/04/10 13:37:33,
ccbin=542606,
timezone=CET,
oid=C-2101f68a-45e9-4f3c-a6da-1337d5574717,
cccountry=N/A,
expmonth=12,
currency=978,
chargetotal=13.99,
approval_code=Y:ECI2/5:Authenticated,
hiddenSharedsecret=sharedsecret,
hiddenTxndatetime=2019:04:10-13:37:08,
expyear=2024,
response_hashExtended=927d3c3108d596c593f74fd79184ece7c33103fe,
response_code_3dsecure=1,
hiddenStorename=12345678,
transactionNotificationURL=https://test.ipg-online.com/webshop/transactionNotification,
tdate=1554903428,
ignore_refreshTime=on,
ccbrand=VISA,
txntype=sale,
paymentMethod=V,
txndatetime=2020:04:10-13:37:08,
cardnumber=(VISA) ... 4979,
ipgTransactionId=84120276797,
status=APPROVED}
All available 3DS response codes you can find here: 3DS response codes
In case you have not used billing and shipping details in your authentication request before, please consider to include them to increase the 3-D Secure authentication approval rate!
In principle, it may occur that 3-D Secure authentications cannot be processed successfully for technical reasons. If one of the systems involved in the authentication process is temporarily not responding, the payment transaction will be processed as a “regular” eCommerce transaction (ECI 7). A liability shift to the card issuer for possible chargebacks is not warranted in this case. If you prefer that such transactions shall not be processed at all, our technical support teams can block them for your Store on request.
Credit card transactions with 3-D Secure hold in a pending status while cardholders search for their authentication method or need to activate their card for 3-D Secure during their shopping experience. During this time when the final transaction result of the transaction is not yet determined, the Gateway sets the Approval Code to „?:waiting 3dsecure“. If the session expires before the cardholder returns from the 3-D Secure dialogue with his bank, the transaction will be shown as “N:-5103:Cardholder did not return from ACS”.
Please note, that the technical process of 3-D Secure transactions differs in some points compared to a normal transaction flow. If you already have an existing shop integration and plan to activate 3-D Secure subsequently, we recommend performing some test transactions on our test environment.
Dynamic 3-D Secure
With the Dynamic 3-D Secure product option you can exclude specific card transactions from the 3-D Secure authentication based on a certain country selection (i.e.: issuing country) while applying the standard 3-D Secure authentication process for other transactions with card from other countries.
You can improve the consumer experience for the cardholders from the selected countries, while the chargeback risk for such transactions is still with you.
If you have ordered this product option, the countries that should be excluded from the 3-D Secure authentication process can be set up for you by your local support team.
In case of specific high-risk transactions, you can override this setting on transaction level and force the 3-D Secure authentication on a Transaction-by-Transaction basis, even if the card used is issued in a country that has been defined by you as a country where 3-D Secure authentication should not be applied. In order to do this, you have to send the parameter override3dsCountryExclusion set to “true”. The country setting will then be ignored and the 3-D Secure authentication process applied.
| Field Name | Description |
|---|---|
override3dsCountryExclusion | Optional parameter to be set either to ‘true’ or ‘false’. Set to ‘true’ if for a transaction you would like to enforce 3-D Secure authentication, despite this country possibly being exempted from authentication due to the merchant configured list of countries, where 3-D Secure is not required. |
Split Authentication
If your business or technical processes require the cardholder authentication to be separated from the payment transaction (authorization), you can use the transaction type payer_auth. This transaction type only performs the authentication (and stores the authentication results).
Example of a payerauth request:
<!-- #include file="ipg-util.asp"-->
<html>
<head><title>IPG Connect Sample for ASP</title></head>
<body>
<p><h1>Order Form</h1></p>
<form method="post" action=" https://test.ipg-online.com/connect/gateway/processing ">
<input type="hidden" name="txntype" value="payer_auth">
<input type="hidden" name="timezone" value="Europe/Berlin"/>
<input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
<input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
<input type="hidden" name="hashExtended" value="<% call createExtendedHash( "13.00","978" ) %>"/>
<input type="hidden" name="storename" value="10123456789" />
<input type="hidden" name="paymentMethod" value="M"/>
<input type="text" name="chargetotal" value="13.00" />
<input type="hidden" name="currency" value="978"/>
<input type="hidden" name="authenticateTransaction" value="true"/>
<input type="submit" value="Submit">
</form>
</body>
</html>
Example of a payerauth response:
{txndate_processed=17/04/20 17:17:32,
ccbin=542606,
timezone=Europe/Berlin,
oid=C-2101f68a-45e9-4f3c-a6da-1337d5574717,
cccountry=N/A,
expmonth=12,
hash_algorithm=HMACSHA256
currency=978,
chargetotal=13.00,
approval_code=Y:ECI2/5:Authenticated,
hiddenSharedsecret=sharedsecret,
hiddenTxndatetime=2020:04:17-17:32:41,
expyear=2024,
response_hash=LarWYFSNgEToq13HlvyslX6hywi2T/nMn8jMY+1kxkI=,
response_code_3dsecure=1,
hiddenStorename=10123456789,
transactionNotificationURL=https://test.ipg-online.com/webshop/transactionNotification,
tdate=1491824253,
ignore_refreshTime=on,
ccbrand=MASTERCARD,
txntype=payer_auth,
paymentMethod=M,
txndatetime=2020:04:17-17:32:41,
cardnumber=(MASTERCARD) ... 4979,
ipgTransactionId=84120276797,
status=APPROVED}
In a second step, you can then submit the payment transaction (sale or preauth) and reference to the prior authentication using the igpTransactionId from the payer_auth response.
Updated about 2 months ago
