3-D Secure

Introduction

When using our Gateway and Fiserv as the 3-D Secure provider, the authentication is performed in-line with the existing transaction flow. The process starts by performing a typical authorization or sale request with a desire to perform 3-D Secure authentication in the request.

The authorization is then placed into a WAITING status until the authentication process is completed. During authentication, the merchant may be required to update the original transaction request one or more times in order to move the process flow forward.

At the end of the authentication process, the original transaction is updated with the authentication results and the authorization is completed.

The sequence diagrams below map to the steps in the text that follows. The first diagram is for the frictionless flow. This means the issuer does not require the cardholder to authenticate.

The next diagram shows the flow when your customer has to authenticate, which means their issuer has requested they provide additional authentication details.

Payments API

Step 1: Initiate a payment

Use either the payment card or the payment token to initiate a Primary Payment Transaction.

You can instruct the payment to use 3-D Secure if you want to enforce it. The relevant RequestTypes for 3-D Secure authentication are as follows:

  • PaymentCardPreAuthTransaction
  • PaymentCardSaleTransaction
  • PaymentTokenPreAuthTransaction
  • PaymentTokenSaleTransaction
  • PaymentCardPayerAuthTransaction

This message needs to include the authenticationRequest object in the transaction request message and includes the following values:

AttributeDescription
authenticationTypethe value Secure3DAuthenticationRequest is a default value for 3DS authentication request
termURLIndicates the callback URL where the results of the authentication process should be posted by the ACS server (this is the Access Control Server that executes the cardholder authentication).
methodNotifictionURLIn order to be notified about the 3DSMethod form display completion, you must also submit this element in your transaction request. The URL should be uniquely identifiable, so when there is a notification received on this URL, you should be able to map it with the corresponding transaction. This eliminates any dependency on the Secure3dTransId which you will receive with the 3DSMethod form response. An easy way to ensure correct transaction mapping is to pass a transaction reference as a query string.
challengeIndicatorIn case you would like to influence which authentication flow should be used, you can submit this optional element with one of the values listed below. In case the Challenge Indicator is not sent within your transaction request, the Gateway will populate the default value “01” – No preference.
challengeWindowSizeIf you want to define the size of the challenge window displayed to your customers during the authentication process, you can submit this optional element with one of the values listed below.

Available values for challengeIndicator are:
01 = No preference (You have no preference whether a challenge should be performed. This is the default value)
02 = No challenge requested (You prefer that no challenge should be performed.)
03 = Challenge requested: 3DS Requestor Preference (You prefer that a challenge should be performed)
04 = Challenge requested: Mandate (There are local or regional mandates that mean that a challenge must be performed)
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)

Available values for challengeWindowSize are:

01 = 250 x 400
02 = 390 x 400
03 = 500 x 600
04 = 600 x 400
05 = Full screen

Based on the payment schemes' observation it is highly recommended to use the value "05 - Full screen" only for browser-based flows. Using full screen mode in app-based flows where the authentication of the cardholder happens on a smartphone or tablet might cause time-outs and trigger an error on issuer/ACS side.

📘

It is highly recommended to include also Billing and Shipping details in your transaction request to lower the risk of authentication declines. To do this, ensure you populate the objects in any of the sale or preauth 'requestType' payloads.

The following JSON documents represents an example of a basic Sale transaction request and a Sale request including browser parameters:

{
  "requestType": "PaymentCardSaleTransaction",
    "transactionAmount": {
      "total": "122.04",
      "currency": "USD"
      },
    "paymentMethod": {
      "paymentCard": {
        "number": "403587XXXXXX4977",
        "securityCode": "977",
        "expiryDate": {
        "month": "12",
        "year": "24"
      }   
    }
  },
  “authenticationRequest”: {
    "authenticationType": "Secure3DAuthenticationRequest",
    "termURL": "https://www.mywebshop.com/process3dSecure",
    "methodNotificationURL": "https://www.mywebshop.com/process3dSecureMethodNotification?transactionReferenceNumber=ffffffff-ba0b-539f-8000-016b2343ad7e",
    "challengeIndicator": "01",
    "challengeWindowSize": "01"
  }
}
{
   "requestType":"PaymentCardSaleTransaction",
   "transactionAmount":{
      "total":"12.00",
      "currency":"EUR"
   },
   "paymentMethod":{
      "paymentCard":{
         "number":"401699*******0022",
         "securityCode":"XXX",
         "expiryDate":{
            "month":"12",
            "year":"27"
         }
      }
   },
   "authenticationRequest":{
      "authenticationType":"Secure3DAuthenticationRequest",
      "termURL":"https://test.com/webshop/simulator/secure3d/return",
      "methodNotificationURL":"https://test.test/notify",
      "challengeIndicator":"01",
      "cardHolderBrowserParams":{
         "browserAcceptHeaders":"Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8",
         "browserIP":"85.117.56.12",
         "browserLanguage":"es-419",
         "browserColorDepth":"32",
         "browserScreenHeight":"1080",
         "browserScreenWidth":"1920",
         "browserTimeZone":"-300",
         "browserUserAgent":"Lynx/2.8.4rel.1 libwww-FM/2.14 SSL-MM/1.4.1 OpenSSL/0.9.6c"
      }
   }
} 

Not all Issuers support the collection of browser data using the 3DSMethod Form. In those cases, no data will be posted to the methodNotificationURL, and the flow should continue by posting a status of EXPECTED_BUT_NOT_RECEIVED – see below.

Step 2: 3-D Secure Authentication Response

Our response will include a 3DSMethod element, which generates a hidden iframe that helps to collect the browser data for the issuers. This information adds to the overall consumer profile and helps in identifying potentially fraudulent transactions. It also increases the probability of a frictionless, successful transaction.

You will need to include the 3DSMethod in your website as hidden iframe. No user interface screen is presented to the cardholder.

At this point, a verification request takes place to determine if the 3-D Secure system is functional and the cardholder is enrolled for 3-D Secure. If the 3-D Secure system is not functioning or if the cardholder is not enrolled, the transaction will process normally and be approved or declined by the processing network.

In the above case the transaction status will appear like so:

transactionStatus = `APPROVED` || `DECLINED`

If the cardholder is verified to be enrolled in the 3-D Secure program, then an 'authenticationResponse' object will be included in the transaction response.

While awaiting the response the transaction will have the following transaction status:

transactionStatus = WAITING

The authenticationResponse object will contain the following values:

AttributeValue
type3D_SECURE
version2.1 or 2.2
secure3DMethod/methodFormHTML form data with hidden iFrame used to collect the web browser data for the Issuer.
secure3DMethod/secure3dTransIdA unique identifier for the transaction provided by the Issuer ACS server.

The following JSON document represents an example of a response:

{
  "clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
  "apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
  "ipgTransactionId": "838916029301",
  "transactionType": "SALE",
  "transactionTime": 1518811817,
  "approvedAmount": {
  "total": 122.04,
  "currency": "USD"
},
  "transactionStatus": "WAITING",
  “authenticationResponse”: {
    "type": "3D_SECURE",
    "version": "2.1",
    "secure3dMethod": {
      "methodForm": "<!DOCTYPE iframe SYSTEM "about:legacy-compat">
      <iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame"
      style="width: 1px; height: 1px; display: none;" src="javascript:false;"
      xmlns="http://www.w3.org/1999/xhtml">
      <!--.--> </iframe><form id="tdsMmethodForm"
      name="tdsMmethodForm"
      action=https://localhost.modirum.com:8543/dstests/ACSEmu2
      method="post"
      target="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml">
      <input type="hidden" name="3DSMethodData"
      value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjAwMDAwMDAwLTU2NzYtNTY2My
      04MDAwLTAwMDAw    
MDAwNDFhOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9
      uVVJMIiA6ICJodHRwczovL2xvY2Fs
aG9zdC5tb2RpcnVtLmNvbTo4NTQzL21kcGF5bXBpL
      01lcmNoYW50U2VydmVyP21uPVkmdHhpZD0x
      
NjgwOSZkaWdlc3Q9aSUyQnhhUEF5NWFOcVJRbllqNmozbWFDZlFJbTdFdjJYTm
      kwNnh6YmZNJTJG
R3MlM0QiIH0"/> <input type="hidden"
      name="threeDSMethodData"            
      value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjAwMDAwMDAwLTU2NzYtNTY2
      My04MDAwLTAwMDA
      w
MDAwNDFhOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA
      6ICJodHRwczovL2xvY 2Fs
aG9zdC5tb2RpcnVtLmNvbTo4NTQzL21kcGF5bXBpL01lcm
      NoYW50U2VydmVyP21uPVkmdHhpZD0x
NjgwOSZkaWdlc3Q9aSUyQnhhUEF5NWFOcV
      JRbllqNmozbWFDZlFJbTdFdjJYTmkwNnh6YmZNJTJG
R3MlM0QiIH0"/>
      </form><script type="text/javascript" 
      xmlns="http://www.w3.org/1999/xhtml">
      document.getElementById("tdsMmethodForm").submit(); </script>",
      "secure3dTransId": "3ac7caa7-aa42-2663-791b-2ac05a542c4a"
    }
  }
}

Step 3: 3DSMethod Notification Request & Response

The 3-D Secure 'methodForm' is used to provide details of the cardholder environment to the Issuer Access Control Server (ACS). The methodForm contains the HTML for a hidden iFrame which is to be included in your web page. This will force the information to be automatically posted to the ACS server via Fiserv. The HTML information is a self-contained HTML block that does not need to be modified or posted, as it will be taken care of automatically when the page in which it is inserted is rendered. Alternatively, this can be created on a page which never becomes visible to the cardholder.

If received properly, the response data will be posted to the URL provided in the original methodNotificationURL field and the posted message will contain a threeDSServerTransID field containing the unique ACS transaction id associated with the original request. Note, that the payload for this response will contain a single element called threeDSMethodData. That element will contain a base64 encoded JSON response that contains the threeDSServerTransID field.

Example:

<form name="frm" method="POST" action="{value from methodNotificationURL}">
  <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSJ9">
</form>

Decoded threeDSMethodData:

{"threeDSServerTransID":"3ac7caa7-aa42-2663-791b-2ac05a542c4a"}

The threeDSServerTransID is not required for any further 3DS processing. However, it is recommended to save this value for reference to the 3DS Server in the future if necessary.

It is highly recommended to wait for 10 seconds for the above POST operation to complete and then determine the methodNotificationStatus as follows:

StatusDescription
RECEIVEDYou have submitted the element methodNotificationURL in the initial Sale transaction request and have received the notification from ACS within 10 seconds, you will receive HTTP POST message from ACS, which will contain a unique transaction identifier represented by secure3dTransId
EXPECTED_BUT_NOT_RECEIVEDYou have submitted the element 'methodNotificationURL' in the initial Sale transaction request and have not received the notification from ACS within 10 seconds.
NOT_EXPECTEDYou have NOT submitted the element methodNotificationURL in the initial Sale transaction request.

🚧

There may be occasions where you will observe duplicate responses to your '3DSMethod Notification URL' or 'Term URL', this could be due to duplicate requests being sent from an issuers ACS or perhaps user behaviour within the browser. It is recommended that you build handling into your system, so in the event you receive a duplicate response to your '3DSMethod Notification URL' or 'Term URL' you do not then send an additional/duplicated request to the Gateway.

Frictionless Flow

Step 4: Request to continue with 3DS Authentication

Once the 3DS Method call has been completed, you need to notify the Gateway, that the authentication process can continue by submitting the methodNotificationStatus element with the values based on corresponding conditions from the 3DSMethod form above. This is done by performing a PATCH operation on the original transaction.

You may also include the optional cardholder billing address and the security code at this time.

The following JSON document represents an example of a request to be sent after 3DSMethod form display:

{
  "authenticationType": "Secure3DAuthenticationUpdateRequest",
  "storeId": "12345500000",
  "billingAddress": {
  "company": "Test Company",
  "address1": "5565 Glenridge Conn",
  "address2": "Suite 123",
  "city": "Atlanta",
  "region": "Georgia",
  "postalCode": "30342",
  "country": "USA"
},
  "securityCode": "123",
  "methodNotificationStatus": "RECEIVED"
}

Step 5: Final 3DS Response

When it is determined that a frictionless flow has been performed (i.e. the customer has been fully authenticated by their bank without the need for direct interaction), the 3-D Secure process is completed and transaction authorization is processed.

The transaction response contains a secure3dResponse object and the transaction is either approved or declined.

transactionStatus = APPROVED or DECLINED

The 'secure3dResponse' object will contain the following field: responseCode3dSecure

The following JSON document represents an example of a response you receive from the API indicating, that the authorisation has been successful:

{
  "clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
  "apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
  "ipgTransactionId": "838916029301",
  "transactionType": "SALE",
  "transactionTime": 1518811817,
  "approvedAmount": {
    "total": 122.04,
    "currency": "USD"
    },
  "transactionStatus": "APPROVED",
  "schemeTransactionId": "019078743804756",
  "processor": {
    "responseCode": "00",
    "responseMessage": "APPROVED",
    "authorizationCode": "OK7118"
    },
    "secure3dResponse": {
      "responseCode3dSecure": "1"
    }
  }
}

Challenge Flow

The challenge flow is triggered, when the transaction is not considered as low risk or when the Issuer requires additional authentication by the cardholder. The whole process starts with an initial Authorisation or Sale transaction request through the step where 3DSMethod is displayed, as described in Steps 1 through 4 above.

Step 6: Request to continue with 3DS Authentication

Once the 3DS Method call has been completed, you need to notify the Gateway that the authentication process can continue by submitting the methodNotificationStatus element with the values based on corresponding conditions from the 3DS Method Form above. This is done by performing a PATCH operation on the original transaction.

You may also include the optional cardholder billing address and the security code at this time.

The following JSON document represents an example of a request to be sent after 3DSMethod form display:

{
  "authenticationType": "Secure3D21AuthenticationUpdateRequest",
  "storeId": "12345500000",
  "methodNotificationStatus": "RECEIVED"
}

Step 7: Gateway respond to continue 3DS Authentication

For the challenge flow, the transaction status will be returned as follows:

transactionStatus = "WAITING"

The response will contain an authenticationResponse object with the following fields:

FieldDescription
type3D_SECURE
version2.1 or 2.2
acsURLThe URL to which the 'cReq and 'sessionData' values should be posted for the cardholder challenge to take place.
termURLThe URL where the results of the authentication will be posted.
cReqAn encoded challenge request message returned from the ACS server.
sessionDataAn encoded list of session parameters to be used for authentication. Note that this value may not always be provided.

The following JSON document represents an example of a response:

{
  "clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
  "apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
  "ipgTransactionId": "838916029301",
  "transactionType": "SALE",
  "transactionTime": 1518811817,
  "approvedAmount": {
  "total": 122.04,
  "currency": "USD"
},
  "transactionStatus": "WAITING",
  "authenticationResponse": {
    "type": "3D_SECURE",
    "version": "2.1",
    "params": {
      "acsURL": "https://3ds-acs.test.com/mdpayacs/creq",
      "termURL": "https://www.mywebshop.com/process3dSecure/",
      "cReq": "ewogICAiYWNzVHJhbCIgOiA...wMDAtMDAwMDAwMDA0MWE5Igp9",
      "sessiondata": "50F2156E03083CA665BCB4.."
      }
    }
  }
}

Step 8: Cardholder Challenge

In the next step you need to POST data to the indicated acsURL usually implemented as an auto-submit form. This needs to be implemented within your website. The cardholder will be redirected to the ACS and presented with the UI to collect the authentication details - for example enter one-time-password or perform authentication using their banking app. After the authentication is completed, the consumer is redirected back to your webpage.

You need to POST the cReq and the sessionData values to the URL specified in the acsURL field.

This information is posted using the following field names:

cReqThe entire base64 encoded cReq message as obtained above.
threeDSSessionDataThe entire base64 encoded sessionData message as obtained above.

Example:

<form name="frm" method="POST" action="https://3ds-acs.test.modirum.com/mdpayacs/pareq ">
  <input type=”hidden” name=”creq” value=”ewogICAiYWNzVHJhbCIgOiA...wMDAtMDAwMDAwMDA0MWE5Igp9”>
  <input type=”hidden” name=”threeDSSessionData” value=”50F2156E03083CA665BCB4..”>
</form>

When the authentication is completed, an authentication response will be posted to the URL specified in the termURLfield.

Step 9: Request to complete transaction

After you received the data from the ACS, you need to submit them to the Gateway in cRes element together with the reference to the original transaction. This is done by sending PATCH request to the original transaction and includes the following values:

authenticationTypeSecure3D21AuthenticationUpdateRequest
acsResponse.cResThe cRes data posted to the termURL by the ACS server.

It is highly recommended to include the optional cardholder billing address and the security code at this time.

The following JSON document represents an example of a request with 'cRes' element:

{
  "authenticationType": "Secure3DAuthenticationUpdateRequest",
  "storeId": "12345500000",
  "billingAddress": {
    "company": "Test Company",
    "address1": "5565 Glenridge Conn",
    "address2": "Suite 123"
    "city": "Atlanta",
    "region": "Georgia",
    "postalCode": "30342",
    "country": "USA"
  },
  "securityCode": "123",
  "acsResponse": {
    "cRes": "ewogICAiYWNzUmVmZX…Fuc1N0YXR…IKfQ=="
  }
}

Step 10 – Final response

Since this transaction was initiated as a 'Sale', the authorization is performed as part of this final step, if the authentication was successful.

The transaction response contains a secure3dResponse object and the transaction is either approved or declined.

The secure3dResponse object will contain the following field: responseCode3dSecure

The following JSON document represents an example of a response you receive indicating that the authorization has been successful:

{
  "clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
  "apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
  "ipgTransactionId": "838916029301",
  "transactionType": "SALE",
  "transactionTime": 1518811817,
  "approvedAmount": {
    "total": 122.04,
    "currency": "USD"
  },
  "transactionStatus": "APPROVED",
  "schemeTransactionId": "019078743804756",
  "processor": {
    "responseCode": "00",
    "responseMessage": "APPROVED",
    "authorizationCode": "OK7118"
  },
  "secure3dResponse": {
    "responseCode3dSecure": "1"
  }
}

The full list of available response codes you can find here: 3DS response codes

3DS Requestor Initiated Flow (3RI)

The main purpose of 3DS Requestor Initiated (3RI) flow is to provide additional information to the issuer on how to handle the request in situations where the cardholder is not present.

Typical use cases include:
• To add a card to Card-on-File without payment
• To refresh authentication value before expiration
• To provide additional information for subsequent recurring and MIT payments

As 3RI transactions are performed without a cardholder being in session, a frictionless flow without 3DSMethod is applied.

The authentication request is identified as "3RI" once it contains the following elements:

Parameter Values
secure3DDeviceChannel• 03 = 3RI
secure3DThreeRIIndicator• 01 = Recurring transaction
• 02 = Instalment transaction
• 03 = Add card
• 04 = Maintain card information
• 05 = Account verification
• 06 = Split shipment
• 07 = Top-up
• 08 = Mail Order
• 09 = Telephone Order
• 10 = Trust List status check
• 11 = Other payment
• 12 = Billing Agreement
• 13 = Device Binding status check
• 14 = Card Security Code status check
• 15 = Delayed shipment
• 16 = Split payment

*Note - in case you use the value 01-Recurring or 02-Installment, you must submit 2 additional parameters recurringFrequencyand recurringExpiryas per specification below
*recurringFrequencyIndicates the minimum number of days between authorisations for a recurring or instalment transaction, numeric field with values between 1-9999
* recurringExpiryDate after which no further authorisations for a recurring or installment are performed, if no fixed date is defined, please use the value: "99991231"
Date format accepted: "YYYYMMDD"

The following JSON documents represent the examples of 3RI request with minimum set of elements and API response:

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
  	"total": "1.00",
  	"currency": "EUR"
  },
  "paymentMethod": {
  	"paymentCard": {
  		"number": "414746******0083",
  		"securityCode": "XXX",
  		"expiryDate": {
  			"month": "12",
            "year": "25"
  		}
  	}
  },
  "authenticationRequest": {
    "authenticationType": "Secure3DAuthenticationRequest",
    "termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
    "methodNotificationURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
    "browserJavaScriptEnabled": "true",
    "challengeIndicator": "06",
    "secure3DThreeRIIndicator":"04",
    "secure3DDeviceChannel": "03"
      }
}
{
    "clientRequestId": "fd876084-d887-4b4d-a0f3-6b80f955f8bc",
    "apiTraceId": "ZK0bpgEBwEpY-RJX2IUIjAAAAtw",
    "ipgTransactionId": "84631281580",
    "orderId": "R-6133fa1f-2e3e-4678-955d-060413a855ce",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "VISA",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "12",
                "year": "2025"
            },
            "bin": "414746",
            "last4": "0083",
            "brand": "VISA"
        },
        "paymentMethodType": "PAYMENT_CARD",
        "paymentMethodBrand": "VISA"
    },
    "country": "Singapore",
    "terminalId": "80000860",
    "merchantId": "000102072004393",
    "transactionTime": 1689066407,
    "approvedAmount": {
        "total": 1.00,
        "currency": "EUR",
        "components": {
            "subtotal": 1.00
        }
    },
    "transactionAmount": {
        "total": 1.00,
        "currency": "EUR",
        "components": {
            "subtotal": 1.00
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:721185:4631281580:YYYM:970742",
    "secure3dResponse": {
        "responseCode3dSecure": "1"
    },
    "schemeTransactionId": "234567891234560",
    "processor": {
        "referenceNumber": "319209970742",
        "authorizationCode": "721185",
        "responseCode": "00",
        "responseMessage": "Function performed error-free",
        "avsResponse": {
            "streetMatch": "Y",
            "postalCodeMatch": "Y"
        },
        "securityCodeResponse": "MATCHED"
    }
}

Decoupled Authentication

Decoupled authentication is an authentication method whereby authentication can occur independently from the cardholder’s experience with the 3DS Requestor. For Decoupled Authentication, instead of utilizing the "CReq" and "CRes "messages, the ACS authenticates the cardholder outside of the EMV 3DS protocol.

In case you wish to use this particular authentication method, you must include dedicated input parameters:

decoupledAuthenticationParamsDescription
decMaxTimeIndicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes).
Numeric values between 00001 and 10080 are accepted.
decReqIndIndicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use.
Note: if the element is not provided, the expected action is for the ACS to interpret as "N"
• Y = Decoupled Authentication is supported and is preferred as a primary challenge method if a challenge is necessary
• N = Do not use Decoupled Authentication

The following JSON document represents an example of an authentication request to use Decoupled flow:

{
    "requestType": "PaymentCardSaleTransaction",
    "storeId": "540997003",
    "transactionAmount": {
        "total": "14.00",
        "currency": "USD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethod": {
        "paymentCard": {
            "number": "49999*****90003",
            "securityCode": "1009",
            "cardFunction": "CREDIT",
            "expiryDate": {
                "month": "12",
                "year": "25"
            }
        }
    },
    "authenticationRequest": {
        "authenticationType": "Secure3DAuthenticationRequest",
        "termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
        "methodNotificationURL": "https://test.test/notify",
        "decoupledAuthenticationParams": {
            "decMaxTime": "10",
            "decReqInd": "Y"
        }
    }
}

Once the issuers confirmed they support Decoupled Authentication, the Gateway returns a response in a "WAITING" status, until a confirmation about successful authentication is received:

{
    "clientRequestId": "2838649",
    "apiTraceId": "ZG8ilD1SH3lS2MWu8mcw-QAAAi4",
    "ipgTransactionId": "84438343414",
    "orderId": "R-95c8430a-2948-45f8-9583-093e3b3c04d8",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "VISA",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "12",
                "year": "2025"
            },
            "cardFunction": "CREDIT",
            "bin": "499999",
            "last4": "0003",
            "brand": "VISA"
        },
        "paymentMethodType": "PAYMENT_CARD",
        "paymentMethodBrand": "VISA"
    },
    "transactionTime": 1685004949,
    "transactionAmount": {
        "total": 14.00,
        "currency": "USD",
        "components": {
            "subtotal": 14.00
        }
    },
    "transactionStatus": "WAITING",
    "approvalCode": "?:waiting 3dsecure Decoupled Authentication",
    "authenticationResponse": {
        "type": "3D_SECURE",
        "version": "2.2"
    }
}

After you received a confirmation from the issuer, that the authentication have been successful, you must generate a completion request with PATCHing "ipgTransactionId" you obtained in previous step:

{

    "authenticationType": "Secure3DAuthenticationUpdateRequest",
    "additionalStep": "COMPLETE_DECOUPLED_AUTHENTICATION"

}

Once our 3DSServer received a RReq message from the issuer confirming authentication status, you will receive a response as on example below:

{
    "clientRequestId": "2838649",
    "apiTraceId": "ZG8rJGIX2yqGEUomhImJWgAAADQ",
    "ipgTransactionId": "84438344739",
    "orderId": "R-77153b36-5ccc-4ff8-afef-7364226338cd",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "VISA",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "12",
                "year": "2023"
            },
            "cardFunction": "CREDIT",
            "bin": "499999",
            "last4": "0003",
            "brand": "VISA"
        },
        "paymentMethodType": "PAYMENT_CARD",
        "paymentMethodBrand": "VISA"
    },
    "terminalId": "1588390",
    "merchantId": "939650001885",
    "transactionTime": 1685006889,
    "approvedAmount": {
        "total": 14,
        "currency": "USD",
        "components": {
            "subtotal": 14
        }
    },
    "transactionAmount": {
        "total": 14,
        "currency": "USD",
        "components": {
            "subtotal": 14
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:OK0074:4438344739:PPXX:970629",
    "secure3dResponse": {
        "responseCode3dSecure": "1"
    },
    "schemeTransactionId": "013145568916020",
    "processor": {
        "referenceNumber": "84438344739",
        "authorizationCode": "OK0074",
        "responseCode": "00",
        "network": "VISA",
        "associationResponseCode": "000",
        "responseMessage": "APPROVAL",
        "avsResponse": {
            "streetMatch": "NO_INPUT_DATA",
            "postalCodeMatch": "NO_INPUT_DATA"
        },
        "securityCodeResponse": "NOT_CHECKED"
    },
    "additionalDetails": {
        "additionalResponseData": {
            "cardProductID": "?",
            "associationResponseCodeAdtl": "00",
            "cardBrand": "V"
        }
    }
}

Authentication with external 3DS provider

In case you are using your own / external 3DS service provider and plan to send authorization request to the Gateway, you need to submit the authentication values obtained from your 3DS service provider.

FieldDescription
authenticationTypeUsed for submitting authentication result performed by an external 3-D Secure service provider
cavvAuthentication value obtained in the authentication response from external 3-D Secure service provider
dsTransactionIdAuthentication transaction reference ID, obtained from external 3-D Secure provider
authenticationResponseRepresents the result of the authentication, allowed values are :
Y = fully authenticated transaction,
A = Successful Authentication Attempt;
U = Unable to Authenticate by DS or ACS

Only the following authentication results are eligible to be passed to the authorization host:

Use caseauthenticationResponsecavvresponseCode3dSecure
Fully Authenticated transaction (ECI = 02 & 05)Yvalue1
Successful Authentication Attempt (ECI = 01 & 06)Avalue4
Unable to authenticate on DS or ACS side (ECI07)Ufield must not be submitted6

The following JSON document represents an example of a sale transaction submitted to our Gateway after being fully authenticated by an external service provider:

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
               "total": "12.00",
               "currency": "EUR"
  },
  "paymentMethod": {
               "paymentCard": {
                               "number": "401699XXXX0006",
                               "securityCode": "999",
                               "expiryDate": {
                                   "month": "12",
                                   "year": "24"
                               }
               }
  },
  "authenticationResult": {
      "authenticationType": "Secure3DAuthenticationResult",
      "cavv": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      "dsTransactionId": "5a56fdc9-6d47-5fee-8000-000000296743",
      "authenticationResponse": "Y"
   }
}

The following JSON document represents an example of a response you receive from the Gateway indicating, that the authorization has been successful and flagged as fully authenticated:

{
   "clientRequestId": "97c67e8f-7c2d-421d-9d97-b749206aab06",
   "apiTraceId": "YJPLezoO2XZa9K8QL10bvgAAA98",
   "ipgTransactionId": "84411977859",
   "orderId": "R-941fc643-adae-4468-bc48-26e5099f4367",
   "transactionType": "SALE",
   "transactionOrigin": "ECOM",
   "paymentMethodDetails":    {
      "paymentCard":       {
         "expiryDate":          {
            "month": "12",
            "year": "2024"
         },
         "bin": "401699",
         "last4": "0006",
         "brand": "VISA"
      },
      "paymentMethodType": "PAYMENT_CARD"
   },
   "country": "USA",
   "terminalId": "80000012",
   "merchantId": "520334507229862",
   "transactionTime": 1620298619,
   "approvedAmount":    {
      "total": 12,
      "currency": "EUR",
      "components": {"subtotal": 12}
   },
   "transactionStatus": "APPROVED",
   "secure3dResponse": {"responseCode3dSecure": "1"},
   "schemeTransactionId": "234567891234560",
   "processor":    {
      "referenceNumber": "112610940537",
      "authorizationCode": "005042",
      "responseCode": "00",
      "responseMessage": "Function performed error-free",
      "avsResponse":       {
         "streetMatch": "Y",
         "postalCodeMatch": "Y"
      },
      "securityCodeResponse": "MATCHED"
   }
}

Hosted Payment Page

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.

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 NameDescription
authenticateTransactionOptional 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"/>
threeDSRequestorChallengeIndicatorOptional 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)
threeDSTransTypeThe 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
scaExemptionIndicator1Use 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.
skipTRAThis 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.
oidUse 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.1) only the following characters are allowed:
A-Z, a-z, 0-9, "-"
bnameCustomer's full name
baddr1Customers Billing Address 1, alphanumeric 96 characters max, including spaces
baddr2Customers Billing Address 2, alphanumeric 96 characters max, including spaces
bcityBilling City, 96 characters max, including spaces
bstateBilling State, Province or Territory (if applicable),
bcountryBilling address country, format: 2 or 3 characters ISO Country Code
bzipBilling address ZIP or postal code, alphanumeric 96 characters max, including spaces
phoneCustomer's Phone Number, 32 characters max
emailCustomer'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 NameDescription
override3dsCountryExclusionOptional 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="mode" value="payonly"/>
    <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.


Want a quick overview?