3-D Secure

3-D Secure is an authentication mechanism designed to reduce fraud and chargebacks in relation to Card-Not-Present transactions.

EMVCo in cooperation with major international schemes defined new EMV 3DS specification for the benefit of the entire industry to collaboratively develop the next generation of 3-D Secure protocol. The new version promotes frictionless consumer authentication and enables consumers to authenticate themselves with their card issuer when making card-not-present e-commerce purchases.

EMV 3-D Secure protocol supports app-based authentication and integration with digital wallets, as well as traditional browser-based e-commerce transactions and delivers industry leading security features.

With our Hosted Payment Page solution we can manage the required flows for the authentication process for you.

If you should however prefer to handle this process and the required redirections yourself, the Web Service API allows you to make single API calls for the required steps.

Initial Transaction Request

In case you use the Gateway for 3DS web-based authentication, in the first step you need to submit a verification request with an AuthenticateTransaction parameter set to “true” and indicate which URL the result of the authentication should be sent to with using TermUrl parameter.

If you wish to be notified about 3DSMethod form display completion, you need to submit also an optional element “ThreeDSMethodNotificationURL” 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 "ThreeDSServerTransID", which you will receive with the 3DSMethod form response. An easy way
how to ensure correct transaction mapping is to is to pass a transaction reference as a query string.

For example:
https://www.mywebshop.com/process3dSecureMethodNotification?transactionReferenceNumber=ffffffff-ba0b-539f-8000-016b2343ad7e

The purpose of 3DSMethod is explained below under ‘Sale’ transaction example.

In case you would like to influence which authentication flow should be used, you can submit “Challenge Indicator” element with one of the values listed below. In case Challenge Indicator is not sent within your transaction request, the Gateway will populate the default value “01” – No preference.

Challenge indicator available values for 3DS v2 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)

🚧
It is highly recommended to include also Billing and Shipping details in your transaction request to lower the risk of authentication declines.

In case you would like to define the size of the challenge window displayed to your customers during the authentication process, you can submit optional Challenge Window Size element with one of the values listed below.

"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.

In order to comply with scheme’s data integrity requirements, we highly recommend to include also following conditionally required parameters in your initial authentication request, what can dramatically improve authentication approval rate.

Path	Type	Description
v1:CardHolderBrowserParameters/ v1:BrowserIP	xs:string45max	Cardholder’s browser IP Address
v1:CardHolderBrowserParameters/ v1:BrowserScreenHeight	xs:string	Cardholder’s browser screen height
v1:CardHolderBrowserParameters/ v1:BrowserScreenWidth	xs:string32max	Cardholder’s browser screen width
v1:Billing/ v1:Name	xs:string96max	Cardholder’s name
v1:Billing/ v1:Phone	xs:string32max	Cardholder’s phone number
v1:Billing/ v1:Email	xs:string	Cardholder’s email address
v1:Billing/ v1:Address1	xs:string96max	Cardholder‘s billing address line 1 (street)
v1:Billing/ v1:City	xs:string96max	Cardholder‘s billing address city
v1:Billing/ v1:State	xs:string96max	Cardholder‘s billing address state (if applicable)
v1:Billing/ v1:Zip	xs:string24max	Cardholder‘s billing address postal code
v1:Billing/ v1:Country	Cardholder’s browser IP Address	Cardholder‘s billing address country

The following XML document represents an example of a Sale transaction request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>426588******0049</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>28</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test.webshop.com/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test.ipg-online.com/ipgconfirmation/services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
<ns2:CardHolderBrowserParameters>
      <ns2:BrowserAcceptHeader>Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8</ns2:BrowserAcceptHeader>
      <ns2:BrowserIP>85.117.56.12</ns2:BrowserIP>
      <ns2:BrowserLanguage>en-GB</ns2:BrowserLanguage>
      <ns2:BrowserColorDepth>32</ns2:BrowserColorDepth>
      <ns2:BrowserScreenHeight>1080</ns2:BrowserScreenHeight>
      <ns2:BrowserScreenWidth>1920</ns2:BrowserScreenWidth>
      <ns2:BrowserTimeZone>-300</ns2:BrowserTimeZone>
      <ns2:BrowserUserAgent>Lynx/2.8.4rel.1 libwww-FM/2.14 SSL-MM/1.4.1 OpenSSL/0.9.6c</ns2:BrowserUserAgent>
</ns2:CardHolderBrowserParameters>
               </ns2:CreditCard3DSecure>
                <ns2:Payment>
                    <ns2:ChargeTotal>15.00</ns2:ChargeTotal>
                    <ns2:Currency>EUR</ns2:Currency>
                </ns2:Payment>
                <ns2:Billing>
		   <ns2:Name>Max Mustermann</ns2:Name>
		   <ns2:Address1>Street 123</ns2:Address1>
		   <ns2:Address2>App2</ns2:Address2>
		   <ns2:City>Frankfurt</ns2:City>
		   <ns2:State>Hessen</ns2:State>
		   <ns2:Zip>98765</ns2:Zip>
		   <ns2:Country>Germany</ns2:Country>
		   <ns2:Phone>+4979331234</ns2:Phone>
		   <ns2:Email>[email protected]</ns2:Email>
		</ns2:Billing>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
         <ipgapi:ApprovalCode>?:waiting 3dsecureMethod</ipgapi:ApprovalCode>
         <ipgapi:Brand>VISA</ipgapi:Brand>
         <ipgapi:Country>SGP</ipgapi:Country>
         <ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
         <ipgapi:OrderId>A-2b45e6ab-9456-4e11-a721-95ab325a1011</ipgapi:OrderId>
         <ipgapi:IpgTransactionId>84637755726</ipgapi:IpgTransactionId>
         <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
         <ipgapi:TDate>1695815106</ipgapi:TDate>
         <ipgapi:TDateFormatted>2023.09.27 13:45:06 (CEST)</ipgapi:TDateFormatted>
         <ipgapi:TransactionTime>1695815106</ipgapi:TransactionTime>
         <ipgapi:Secure3DResponse>
            <v1:Secure3DMethod>
               <v1:Secure3DMethodForm><![CDATA[<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="visibility: hidden; width: 1px; height: 1px;" xmlns="http://www.w3.org/1999/xhtml">
    <!--.-->
</iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml">
    <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjNhYjdhYjQ5LWI5ZGQtNWU0My04MDAwLTAwMDAwMWFlMDQ0MyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL3Rlc3QuaXBnLW9ubGluZS5jb20vaXBnY29uZmlybWF0aW9uL3NlcnZpY2VzL3NlY3VyZTNkcz9yZWZlcmVuY2VkVHJhbnNhY3Rpb25JZD04NDYzNzc1NTcyNiIgfQ"/>
    <input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjNhYjdhYjQ5LWI5ZGQtNWU0My04MDAwLTAwMDAwMWFlMDQ0MyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL3Rlc3QuaXBnLW9ubGluZS5jb20vaXBnY29uZmlybWF0aW9uL3NlcnZpY2VzL3NlY3VyZTNkcz9yZWZlcmVuY2VkVHJhbnNhY3Rpb25JZD04NDYzNzc1NTcyNiIgfQ"/>
    <script type="text/javascript">
				document.getElementById("tdsMmethodForm").submit();
			</script>
</form>]]></v1:Secure3DMethodForm>
               <v1:Secure3DServerTransactionId>28181571</v1:Secure3DServerTransactionId>
            </v1:Secure3DMethod>
         </ipgapi:Secure3DResponse>
      </ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

🚧
In case you submitted 'OrderId' element in your request, please make sure to include only allowed characters: A-Z, a-z, 0-9, "-"

3DS Method

If the response from the Gateway contains 3DSMethod element, it 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.

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

Frictionless Flow

When a transaction is considered to be a low-risk or an exemption is requested, a frictionless flow is applied. In such case the Gateway proceeds with the authorization without additional authentication of the cardholder.

Once the 3DSMethod call has been completed, you MUST notify the Gateway, that the authentication process can continue by submitting the Secure3DMethodNotificationStatus element with the values based on corresponding conditions:

• Secure3DMethodNotificationStatus = “RECEIVED” in case you have submitted the element ThreeDSMethodNotificationURL 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 threeDSServerTransID
• Secure3DMethodNotificationStatus = “EXPECTED_BUT_NOT_RECEIVED” in case you have submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction request and have not received the notification from ACS within 10 seconds
• Secure3DMethodNotificationStatus = “NOT_EXPECTED” in case you have NOT submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction request.

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

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>120995000</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCard3DSecure>
                    <ns2:Secure3DMethodNotificationStatus>RECEIVED</ns2: Secure3DMethodNotificationStatus>
                </ns2:CreditCard3DSecure>
                <ns2:TransactionDetails>
                    <ns2:IpgTransactionId>8383394827</ns2:IpgTransactionId>
                </ns2:TransactionDetails>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following XML document represents an example of a response including ResponseCode3dSecureelement indicating that the authorization has been successful and fully authenticated:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
 <SOAP-ENV:Header/>
 <SOAP-ENV:Body>
 <ipgapi:IPGApiOrderResponse
 xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
 xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
 xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
 <ipgapi:ApprovalCode>Y:416502:0014750513:PPXM:4625106408</ipgapi:ApprovalCode>
 <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
 <ipgapi:Brand>VISA</ipgapi:Brand>
 <ipgapi:OrderId>A-52421c39-69c4-4b2d-959d-9fdcd3a9420a</ipgapi:OrderId>
 <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
 <ipgapi:ProcessorApprovalCode>416502</ipgapi:ProcessorApprovalCode>
 <ipgapi:ProcessorReceiptNumber>6408</ipgapi:ProcessorReceiptNumber>
 <ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
 <ipgapi:ProcessorTraceNumber>462510</ipgapi:ProcessorTraceNumber>
 <ipgapi:ReferencedTDate>1407373209</ipgapi:ReferencedTDate>
 <ipgapi:TDate>1407373209</ipgapi:TDate>
 <ipgapi:TDateFormatted>2014.08.07 03:00:09(CEST)</ipgapi:TDateFormatted>
 <ipgapi:TerminalID>54000666</ipgapi:TerminalID>
 <ipgapi:Secure3DResponse>
     <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
 </ipgapi:Secure3DResponse>
 </ipgapi:IPGApiOrderResponse>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Challenge Flow

Challenge flow is applied when the transaction is not considered to be a low-risk or in case the issuer requires additional authentication of the cardholder. The whole process starts with initial “Sale” transaction request until the step where 3DS Method is displayed.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>426588******0049</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>28</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test.webshop.com/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test.ipg-online.com/ipgconfirmation/services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
<ns2:CardHolderBrowserParameters>
      <ns2:BrowserAcceptHeader>Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8</ns2:BrowserAcceptHeader>
      <ns2:BrowserIP>85.117.56.12</ns2:BrowserIP>
      <ns2:BrowserLanguage>en-GB</ns2:BrowserLanguage>
      <ns2:BrowserColorDepth>32</ns2:BrowserColorDepth>
      <ns2:BrowserScreenHeight>1080</ns2:BrowserScreenHeight>
      <ns2:BrowserScreenWidth>1920</ns2:BrowserScreenWidth>
      <ns2:BrowserTimeZone>-300</ns2:BrowserTimeZone>
      <ns2:BrowserUserAgent>Lynx/2.8.4rel.1 libwww-FM/2.14 SSL-MM/1.4.1 OpenSSL/0.9.6c</ns2:BrowserUserAgent>
</ns2:CardHolderBrowserParameters>
               </ns2:CreditCard3DSecure>
                <ns2:Payment>
                    <ns2:ChargeTotal>15.00</ns2:ChargeTotal>
                    <ns2:Currency>EUR</ns2:Currency>
                </ns2:Payment>
                <ns2:Billing>
		   <ns2:Name>Max Mustermann</ns2:Name>
		   <ns2:Address1>Street 123</ns2:Address1>
		   <ns2:Address2>App2</ns2:Address2>
		   <ns2:City>Frankfurt</ns2:City>
		   <ns2:State>Hessen</ns2:State>
		   <ns2:Zip>98765</ns2:Zip>
		   <ns2:Country>Germany</ns2:Country>
		   <ns2:Phone>+4979331234</ns2:Phone>
		   <ns2:Email>[email protected]</ns2:Email>
		</ns2:Billing>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
         <ipgapi:ApprovalCode>?:waiting 3dsecureMethod</ipgapi:ApprovalCode>
         <ipgapi:Brand>VISA</ipgapi:Brand>
         <ipgapi:Country>SGP</ipgapi:Country>
         <ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
         <ipgapi:OrderId>A-2b45e6ab-9456-4e11-a721-95ab325a1011</ipgapi:OrderId>
         <ipgapi:IpgTransactionId>84637755726</ipgapi:IpgTransactionId>
         <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
         <ipgapi:TDate>1695815106</ipgapi:TDate>
         <ipgapi:TDateFormatted>2023.09.27 13:45:06 (CEST)</ipgapi:TDateFormatted>
         <ipgapi:TransactionTime>1695815106</ipgapi:TransactionTime>
         <ipgapi:Secure3DResponse>
            <v1:Secure3DMethod>
               <v1:Secure3DMethodForm><![CDATA[<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="visibility: hidden; width: 1px; height: 1px;" xmlns="http://www.w3.org/1999/xhtml">
    <!--.-->
</iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml">
    <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjNhYjdhYjQ5LWI5ZGQtNWU0My04MDAwLTAwMDAwMWFlMDQ0MyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL3Rlc3QuaXBnLW9ubGluZS5jb20vaXBnY29uZmlybWF0aW9uL3NlcnZpY2VzL3NlY3VyZTNkcz9yZWZlcmVuY2VkVHJhbnNhY3Rpb25JZD04NDYzNzc1NTcyNiIgfQ"/>
    <input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjNhYjdhYjQ5LWI5ZGQtNWU0My04MDAwLTAwMDAwMWFlMDQ0MyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL3Rlc3QuaXBnLW9ubGluZS5jb20vaXBnY29uZmlybWF0aW9uL3NlcnZpY2VzL3NlY3VyZTNkcz9yZWZlcmVuY2VkVHJhbnNhY3Rpb25JZD04NDYzNzc1NTcyNiIgfQ"/>
    <script type="text/javascript">
				document.getElementById("tdsMmethodForm").submit();
			</script>
</form>]]></v1:Secure3DMethodForm>
               <v1:Secure3DServerTransactionId>28181571</v1:Secure3DServerTransactionId>
            </v1:Secure3DMethod>
         </ipgapi:Secure3DResponse>
      </ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Once the 3DS Method call has been completed, you MUST notify the Gateway that the authentication process can continue by submitting the Secure3DMethodNotificationStatus element with the values based on corresponding conditions:

• Secure3DMethodNotificationStatus = “RECEIVED” in case you have submitted the element ThreeDSMethodNotificationURL 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 threeDSServerTransID
• Secure3DMethodNotificationStatus = “EXPECTED_BUT_NOT_RECEIVED” in case you have submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction request and have not received the notification from ACS within 10 seconds
• Secure3DMethodNotificationStatus = “NOT_EXPECTED” in case you have NOT submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction request

The following XML document represents an example of a request to process 3DSMethod call and a response. Our Gateway verifies the response and provides the result back to you, including the challenge result data.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>120995000</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCard3DSecure>
                    <ns2:Secure3DMethodNotificationStatus>RECEIVED</ns2: Secure3DMethodNotificationStatus>
                </ns2:CreditCard3DSecure>
                <ns2:TransactionDetails>
                    <ns2:IpgTransactionId>8383394827</ns2:IpgTransactionId>
                </ns2:TransactionDetails>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiOrderResponse
            xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
            xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting 3dsecure</ipgapi:ApprovalCode>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-4b9804e6410b84475809e59e1b26</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383394827</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1493130774</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.04.25 16:32:54(CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1493130774</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:Secure3DVerificationResponse>
<v1:VerificationRedirectResponse>
  <v1:AcsURL>https://3ds-acs.test.simulator.com/mdpayacs/creq</v1:AcsURL>
  <v1:CReq>ewogICAiYWNzVHJhbCIgOiA...wMDAtMDAwMDAwMDA0MWE5Igp9</v1:CReq>
  <v1:TermUrl>https://www.mywebshop.com/process3dSecure/</v1:TermUrl>
</v1:VerificationRedirectResponse>
</v1:Secure3DVerificationResponse>
            </ipgapi:Secure3DResponse>
        </ipgapi:IPGApiOrderResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the next step you have to POST the data to the indicated URL usually implemented as auto-submit form. This needs to be implemented within your website. We recommend you to POST the challenge request element without capitals (e.g. creq) to avoid any problems in a communication with the ACS.

<form name="frm" method="POST" action="https://3ds-acs.simulator.com/mdpayacs/creq ">
  <input type=”hidden” name=”creq” value=”ewogICAiYWNzOiA...wMDAtMDAwMDAwMDA0MWE5Igp9”>
  <input type=”hidden” name=”threeDSSessionData” value=”50F2156E033CA665BCB4..”>
</form>

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 authentication completion the consumer is redirected back to your webpage.
After you received the data from the ACS you need to submit them back to the Gateway in CRes element together with the reference to the original transaction.

The following XML document represents an example of a request with CRes element. Since this transaction was initiated as "Sale", the authorization is performed as part of this step if the authentication was successful.

You receive a response from the Gateway indicating, that the authorization has been successful.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>120995000</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>              
                <ns2:CreditCard3DSecure>
                    <ns2:Secure3DRequest>
                        <ns2:Secure3DAuthenticationRequest>
                         <ns2:AcsResponse>
                           <ns2:CRes>ewogICAiYWNzUmVmZX…Fuc1N0YXR…IKfQ==</ns2:CRes>
                         </ns2:AcsResponse>
                        </ns2:Secure3DAuthenticationRequest>
                    </ns2:Secure3DRequest>
                </ns2:CreditCard3DSecure>
                <ns2:TransactionDetails>
                    <ns2:IpgTransactionId>8383394827</ns2:IpgTransactionId>
                </ns2:TransactionDetails>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiOrderResponse
            xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
            xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:ApprovalCode>Y:416502:0014750513:PPXM:4625106408</ipgapi:ApprovalCode>
            <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
            <ipgapi:Brand>VISA</ipgapi:Brand>
            <ipgapi:OrderId>A-52421c39-69c4-4b2d-959d-9fdcd3a9420a</ipgapi:OrderId>
            <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
            <ipgapi:ProcessorApprovalCode>416502</ipgapi:ProcessorApprovalCode>
            <ipgapi:ProcessorReceiptNumber>6408</ipgapi:ProcessorReceiptNumber>
            <ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
            <ipgapi:ProcessorTraceNumber>462510</ipgapi:ProcessorTraceNumber>
            <ipgapi:ReferencedTDate>1407373209</ipgapi:ReferencedTDate>
            <ipgapi:TDate>1407373209</ipgapi:TDate>
            <ipgapi:TDateFormatted>2014.08.07 03:00:09 (CEST)</ipgapi:TDateFormatted>
            <ipgapi:TerminalID>54000666</ipgapi:TerminalID>
            <ipgapi:Secure3DResponse>
                <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
            </ipgapi:Secure3DResponse>
        </ipgapi:IPGApiOrderResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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 team can block them for your Store upon request.

3DS Request Initiated (3RI) Flow

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.

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>4012****2011004</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>27</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test.com/webshop/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test.services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>02</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
<ns2:ThreeDSRequestorAuthenticationIndicator>01</ns2:ThreeDSRequestorAuthenticationIndicator>
<ns2:deviceChannel>03</ns2:deviceChannel>
<ns2:threeRIInd>05</ns2:threeRIInd>
               </ns2:CreditCard3DSecure>
                <ns2:Payment>
                    <ns2:ChargeTotal>15.00</ns2:ChargeTotal>
                    <ns2:Currency>EUR</ns2:Currency>
                </ns2:Payment>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:309372:4484275011:YYYM:418881</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-504a5ebf-6424-41af-bfd1-8f9eaca23378</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84484275011</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>309372</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>         <ipgapi:ProcessorReferenceNumber>306016418881</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>234567891234560</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1677686964</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.03.01 17:09:24 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000012</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1677686964</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
   <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
      </ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Decoupled Authentication

Decoupled Authentication is an authentication method whereby authentication can occur independent from the cardholder’s experience. It may happen that, in a challenge situation, issuers want to reach out to authenticate their cardholders outside of the EMV 3DS message flows.

📘
Please note, that not all the issuers support decoupled authentication and the processing as described below demonstrates the case, where this flow is supported.

In the first step you need to indicate, you wish to perform customer authentication using decoupled flow with including ThreeDSDecoupledAuthenticationParameters as highlighted below.

The following XML document represents an example of a decoupled authentication using minimal set of elements:

</SOAP-ENV:Envelope>ope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns4:IPGApiOrderRequest xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
         <ns2:Transaction>
            <ns2:CreditCardTxType>
               <ns2:StoreId>540997003</ns2:StoreId>
               <ns2:Type>sale</ns2:Type>
            </ns2:CreditCardTxType>
            <ns2:CreditCardData>
               <ns2:CardNumber>499999****0003</ns2:CardNumber>
               <ns2:ExpMonth>12</ns2:ExpMonth>
               <ns2:ExpYear>27</ns2:ExpYear>
               <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
            </ns2:CreditCardData>
            <ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test3.ipg-online.com/webshop/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test3.ipg-online.com/ipgconfirmation/services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
            </ns2:CreditCard3DSecure>
           <ns2:ThreeDSDecoupledAuthenticationParameters>
               <ns2:ThreeDSRequestorDecReqInd>Y</ns2:ThreeDSRequestorDecReqInd>
               <ns2:ThreeDSRequestorDecMaxTime>14</ns2:ThreeDSRequestorDecMaxTime>
           </ns2:ThreeDSDecoupledAuthenticationParameters>
            <ns2:Payment>
               <ns2:ChargeTotal>199</ns2:ChargeTotal>
               <ns2:Currency>USD</ns2:Currency>
            </ns2:Payment>
            <ns2:Billing>
              <ns2:Phone>001-6642345678</ns2:Phone>
            </ns2:Billing>
         </ns2:Transaction>
      </ns4:IPGApiOrderRequest>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Unlike a standard challenge flow, the customer authentication is performed outside of EMV protocol, therefore it does not contain CReq and CRes message types.
Transaction remains in waiting status until you submit a request to our Gateway to complete the authentication.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting 3dsecure Decoupled Authentication</ipgapi:ApprovalCode>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>GMA</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-ef8a6705-e7d4-4479-bc80-0720e2a63468</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84443660650</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1689165865</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.07.12 14:44:25 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1689165865</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:Secure3DVerificationResponse>
<v1:VerificationRedirectResponse/>
</v1:Secure3DVerificationResponse>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Once you received the feedback, that you consumers have successfully authenticated themselves, you must submit API request including parameter Secure3DAdditionalStep as on the example below. It is highly recommended to submit CVV value in the request again, as the Gateway cannot store it while waiting for a decoupled authentication to be completed.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns3:IPGApiOrderRequest xmlns:ns3="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ns4="http://ipg-online.com/ipgapi/schemas/a1">
         <ns2:Transaction>
            <ns2:CreditCardTxType>
               <ns2:StoreId>540997003</ns2:StoreId>
               <ns2:Type>sale</ns2:Type>
            </ns2:CreditCardTxType>
            <ns2:CreditCardData>
               <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
            </ns2:CreditCardData>
            <ns2:CreditCard3DSecure>
<ns2:Secure3DAdditionalStep>COMPLETE_DECOUPLED_AUTHENTICATION</ns2:Secure3DAdditionalStep>
            </ns2:CreditCard3DSecure>
            <ns2:Payment/>
            <ns2:TransactionDetails>
               <ns2:IpgTransactionId>84340519820</ns2:IpgTransactionId>
            </ns2:TransactionDetails>
         </ns2:Transaction>
      </ns3:IPGApiOrderRequest>
   </soap:Body>
</soap:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:OK1449:4438118015:PPXX:937657</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>GMA</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-06510028-eb05-4dc7-8b35-1e41556198d5</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84438118015</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>OK1449</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>X</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>84438118015</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorNetworkInformation>VISA</ipgapi:ProcessorNetworkInformation>
<ipgapi:ProcessorAssociationResponseCode>000</ipgapi:ProcessorAssociationResponseCode>
<ipgapi:ProcessorResponseMessage>APPROVAL</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>013144535118039</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1684903630</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.05.24 06:47:10 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>1588390</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1684903630</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

Authentication with external 3DS Service provider

In case you are using your own or 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.

The following XML document represents an example of a sale transaction submitted to our Gateway after being fully authenticated by an external service provider and corresponding API response.

<?xml version="1.0" encoding="UTF-8"?><ns4:IPGApiOrderRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
    <ns3:Transaction>
        <ns3:CreditCardTxType>
            <ns3:Type>sale</ns3:Type>
        </ns3:CreditCardTxType>
        <ns3:CreditCardData>
            <ns3:CardNumber>403587XXXXXX4977</ns3:CardNumber>
            <ns3:ExpMonth>12</ns3:ExpMonth>
            <ns3:ExpYear>27</ns3:ExpYear>
            <ns3:CardCodeValue>XXX</ns3:CardCodeValue>
        </ns3:CreditCardData>
    <ns3:CreditCard3DSecure>
      <ns3:AuthenticationValue>xgQO57LRAAAAAAAAAA=</ns3:AuthenticationValue>
      <ns3:Secure3D2TransactionStatus>Y</ns3:Secure3D2TransactionStatus>
      <ns3:Secure3D2AuthenticationResponse>Y</ns3:Secure3D2AuthenticationResponse>
      <ns3:Secure3DProtocolVersion>2.2.0</ns3:Secure3DProtocolVersion>
      <ns3:DirectoryServerTransactionId>925a0317-9143-5130-8000-0000000f8742
</ns3:DirectoryServerTransactionId>      
    </ns3:CreditCard3DSecure>
        <ns3:Payment>
            <ns3:ChargeTotal>1.00</ns3:ChargeTotal>
            <ns3:Currency>978</ns3:Currency>
        </ns3:Payment>
        <ns3:TransactionDetails>
            <ns3:OrderId>API-Test-Order123456789</ns3:OrderId>
        </ns3:TransactionDetails>
    </ns3:Transaction>
</ns4:IPGApiOrderRequest>

<?xml version="1.0" encoding="UTF-8"?><ipgapi:IPGApiOrderResponse 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
    <ipgapi:ApprovalCode>Y:282266:8385028528:PPXM:3056131932</ipgapi:ApprovalCode>
    <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
    <ipgapi:Brand>VISA</ipgapi:Brand>
    <ipgapi:Country>USA</ipgapi:Country>
    <ipgapi:CommercialServiceProvider>TELECASH</ipgapi:CommercialServiceProvider>
    <ipgapi:OrderId>API-Test-Order123456789</ipgapi:OrderId>
    <ipgapi:IpgTransactionId>8385028528</ipgapi:IpgTransactionId>
    <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
    <ipgapi:ProcessorApprovalCode>282266</ipgapi:ProcessorApprovalCode>
    <ipgapi:ProcessorReceiptNumber>1932</ipgapi:ProcessorReceiptNumber>
    <ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
    <ipgapi:ProcessorReferenceNumber>55063291</ipgapi:ProcessorReferenceNumber>
    <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
    <ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
    <ipgapi:ProcessorTraceNumber>305613</ipgapi:ProcessorTraceNumber>
    <ipgapi:TDate>1553773696</ipgapi:TDate>
    <ipgapi:TDateFormatted>2019.03.28 12:48:16 (CET)</ipgapi:TDateFormatted>
    <ipgapi:TerminalID>54000668</ipgapi:TerminalID>
    <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
    <ipgapi:TransactionTime>1553773696</ipgapi:TransactionTime>
    <ipgapi:Secure3DResponse>
        <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
    </ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

The following XML document represents an example of a sale transaction submitted to our Gateway after successful authentication attempt and its corresponding response:

<?xml version="1.0" encoding="UTF-8"?><ns4:IPGApiOrderRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
    <ns3:Transaction>
        <ns3:CreditCardTxType>
            <ns3:Type>sale</ns3:Type>
        </ns3:CreditCardTxType>
        <ns3:CreditCardData>
            <ns3:CardNumber>403587XXXXXX4977</ns3:CardNumber>
            <ns3:ExpMonth>12</ns3:ExpMonth>
            <ns3:ExpYear>27</ns3:ExpYear>
            <ns3:CardCodeValue>XXX</ns3:CardCodeValue>
        </ns3:CreditCardData>
   <ns3:CreditCard3DSecure>
     <ns3:AuthenticationValue>xgQO57LRAAAAAAA=</ns3:AuthenticationValue>    
     <ns3:Secure3D2AuthenticationResponse>A</ns3:Secure3D2AuthenticationResponse>
     <ns3:Secure3DProtocolVersion>2.2.0</ns3:Secure3DProtocolVersion>
     <ns3:DirectoryServerTransactionId>123456</ns3:DirectoryServerTransactionId>   
   </ns3:CreditCard3DSecure>
        <ns3:Payment>
            <ns3:ChargeTotal>1.00</ns3:ChargeTotal>
            <ns3:Currency>978</ns3:Currency>
        </ns3:Payment>
        <ns3:TransactionDetails>
            <ns3:OrderId>API-Test-Order12345678910</ns3:OrderId>
        </ns3:TransactionDetails>
    </ns3:Transaction>
</ns4:IPGApiOrderRequest>

<?xml version="1.0" encoding="UTF-8"?><ipgapi:IPGApiOrderResponse 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
    <ipgapi:ApprovalCode>Y:282266:8385028528:PPXM:3056131932</ipgapi:ApprovalCode>
    <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
    <ipgapi:Brand>VISA</ipgapi:Brand>
    <ipgapi:Country>USA</ipgapi:Country>
    <ipgapi:CommercialServiceProvider>TELECASH</ipgapi:CommercialServiceProvider>
    <ipgapi:OrderId>API-Test-Order12345678910</ipgapi:OrderId>
    <ipgapi:IpgTransactionId>8385028528</ipgapi:IpgTransactionId>
    <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
    <ipgapi:ProcessorApprovalCode>282266</ipgapi:ProcessorApprovalCode>
    <ipgapi:ProcessorReceiptNumber>1932</ipgapi:ProcessorReceiptNumber>
    <ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
    <ipgapi:ProcessorReferenceNumber>55063291</ipgapi:ProcessorReferenceNumber>
    <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
    <ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
    <ipgapi:ProcessorTraceNumber>305613</ipgapi:ProcessorTraceNumber>
    <ipgapi:TDate>1553773696</ipgapi:TDate>
    <ipgapi:TDateFormatted>2019.03.28 12:48:16 (CET)</ipgapi:TDateFormatted>
    <ipgapi:TerminalID>54000668</ipgapi:TerminalID>
    <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
    <ipgapi:TransactionTime>1553773696</ipgapi:TransactionTime>
    <ipgapi:Secure3DResponse>
        <v1:ResponseCode3dSecure>4</v1:ResponseCode3dSecure>
    </ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

The following Secure3D2AuthenticationResponse element values are available:
Y = Authentication successful
U = Authentication could not be performed due to technical or other problem on DS or ACS side
A = Attempts processing performed; not authenticated, but a proof of attempted authentication is provided

🚧
Failed or rejected authentications are not allowed to be passed to the authorization platform and will be declined by the Gateway.

Use Case	Secure3D2 AuthenticationResponse	Secure3D2 TransactionStatus	AuthenticationValue (CAVV/AAV)	IPG3dsecure response code	Gateway action
Fully authenticated transaction (ECI2, ECI5)	Y	Y	Value	1	the authorization message is sent to the authorization host
Successful Attempt to authenticate the cardholder (ECI1, ECI6)	A	Field Must Not Be Submitted	Value	4	The authorization message is sent to the authorization host
Unable to authenticate due to issue on DS or ACS side (ECI7)	U	Field Must Not Be Submitted	Field Must Not Be Submitted	6	The authorization message is sent to the authorization host, if ECI7 transactions are not blocked in store configuration

Non-Payment Authentication (NPA)

For cases, where you prefer to register your customers’ credit cards on file without charging them in the same session, you can submit a payerAuth request to our Gateway with a value ‘02’ in threeDSEmvCoMessageCategory element.
As it is mandatory to use Strong Customer Authentication (SCA) for all new cards added to Card-On-File, NPA transaction request must include ThreeDSRequestorChallengeIndicator value ’04’ and ThreeDSRequestorAuthenticationIndicator value ‘04=Add card’.

The following represents an example of a ‘payerAuth’ request with basic set of elements:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>payerAuth</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>40169*******0014</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>27</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:CreditCard3DSecure>                 
         <ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:ThreeDSRequestorChallengeIndicator>04</ns2:ThreeDSRequestorChallengeIndicator>             
<ns2:ThreeDSEmvCoMessageCategory>02</ns2:ThreeDSEmvCoMessageCategory>
<ns2:TermUrl>https://mywebshop.com</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://mywebshop.com/notification</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
<ns2:ThreeDSRequestorAuthenticationIndicator>04</ns2:ThreeDSRequestorAuthenticationIndicator>
                </ns2:CreditCard3DSecure>                
                <ns2:Payment>
                    <ns2:ChargeTotal>0.00</ns2:ChargeTotal>
                    <ns2:Currency>978</ns2:Currency>
                </ns2:Payment>
              </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
         <ipgapi:ApprovalCode>Y:ECI2/5:Authenticated</ipgapi:ApprovalCode>
         <ipgapi:Brand>VISA</ipgapi:Brand>
         <ipgapi:Country>USA</ipgapi:Country>
         <ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
         <ipgapi:OrderId>A-f2adf245-7a38-4729-b9e0-1fb7f1296abd</ipgapi:OrderId>
         <ipgapi:IpgTransactionId>84572410148</ipgapi:IpgTransactionId>
         <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
         <ipgapi:TDate>1630925618</ipgapi:TDate>
         <ipgapi:TDateFormatted>2021.09.06 12:53:38 (CEST)</ipgapi:TDateFormatted>
         <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
         <ipgapi:TransactionTime>1630925618</ipgapi:TransactionTime>
         <ipgapi:Secure3DResponse>
            <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
         </ipgapi:Secure3DResponse>
      </ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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.

The following represents an example of a payerAuth request with minimal set of elements:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>payerAuth</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>40169*******0014</ns2:CardNumber>
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>27</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:CreditCard3DSecure>                  
                  <ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>              
<ns2:ThreeDSEmvCoMessageCategory>01</ns2:ThreeDSEmvCoMessageCategory>
<ns2:TermUrl>https://mywebshop.com</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://mywebshop.com/notification</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
                </ns2:CreditCard3DSecure>                
                <ns2:Payment>
                    <ns2:ChargeTotal>10.00</ns2:ChargeTotal>
                    <ns2:Currency>978</ns2:Currency>
                </ns2:Payment>
              </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

For cases where a frictionless flow has been performed you will receive the following response directly:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
         <ipgapi:ApprovalCode>Y:ECI2/5:Authenticated</ipgapi:ApprovalCode>
         <ipgapi:Brand>VISA</ipgapi:Brand>
         <ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
         <ipgapi:OrderId>A-6e3857f6-cc58-47d4-902c-d00283ed56ae</ipgapi:OrderId>
         <ipgapi:IpgTransactionId>84484279058</ipgapi:IpgTransactionId>
         <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
         <ipgapi:TDate>1677754450</ipgapi:TDate>
         <ipgapi:TDateFormatted>2023.03.02 11:54:10 (CET)</ipgapi:TDateFormatted>
         <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
         <ipgapi:TransactionTime>1677754450</ipgapi:TransactionTime>
         <ipgapi:Secure3DResponse>
            <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
         </ipgapi:Secure3DResponse>
      </ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

For cases where a challenge flow has been requested, please follow the process as described in the chapter "Challenge Flow" of this guide.

In a second step, you can then submit the payment transaction (sale or preauth) and reference to the prior authentication using the igpTransactionIdfrom the 'payerAuth' response.

The following XML document represents an example of a “sale” request and response with minimal set of elements:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>1109950006</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
   <ns2:CreditCardData>
     			<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
		   </ns2:CreditCardData>
                <ns2:TransactionDetails>
                	<ns2:IpgTransactionId>84484279058</ns2:IpgTransactionId>
                </ns2:TransactionDetails>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:245155:4484283852:YYYM:419397</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-5f2b2d63-024a-47a7-abc2-c13b3c5afb80</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84484279058</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>245155</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>         <ipgapi:ProcessorReferenceNumber>306209419397</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>234567891234560</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1677836064</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.03.03 10:34:24 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000012</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1677836064</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
      <v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3-D Secure

🚧
It is highly recommended to include also Billing and Shipping details in your transaction request to lower the risk of authentication declines.

🚧
In case you submitted 'OrderId' element in your request, please make sure to include only allowed characters: A-Z, a-z, 0-9, "-"

📘
Please note, that not all the issuers support decoupled authentication and the processing as described below demonstrates the case, where this flow is supported.

🚧
Failed or rejected authentications are not allowed to be passed to the authorization platform and will be declined by the Gateway.

🚧It is highly recommended to include also Billing and Shipping details in your transaction request to lower the risk of authentication declines.

🚧In case you submitted 'OrderId' element in your request, please make sure to include only allowed characters: A-Z, a-z, 0-9, "-"

📘Please note, that not all the issuers support decoupled authentication and the processing as described below demonstrates the case, where this flow is supported.

🚧Failed or rejected authentications are not allowed to be passed to the authorization platform and will be declined by the Gateway.

API Products

Point of Sale

Developer

Resources

🚧
It is highly recommended to include also Billing and Shipping details in your transaction request to lower the risk of authentication declines.

🚧
In case you submitted 'OrderId' element in your request, please make sure to include only allowed characters: A-Z, a-z, 0-9, "-"

📘
Please note, that not all the issuers support decoupled authentication and the processing as described below demonstrates the case, where this flow is supported.

🚧
Failed or rejected authentications are not allowed to be passed to the authorization platform and will be declined by the Gateway.