Implementing a 3DS Integration using the Authentication API

This guide outlines all the steps that are required to add 3DS to your gateway integration using the Authentication API, including how to use the authentication result to process a payment.

Step 1: Initiate Authentication

The Initiate Authentication operation is used to determine the 3DS versions available to you for a given card, which will be based on

  • the 3DS versions configured on your merchant profile, for example, 3DS1 or 3DS2
  • the card type
  • preferences you have indicated in the request
  • the outcome of requests the gateway has sent to the relevant authentication providers to check availability or support for the given card, and
  • the gateway's 3DS transaction filtering rules configured by you or your payment service provider.

The operation also enables any background activities (such as a ACS Method call) to be carried out for purposes such as gathering additional payer data to support a subsequent Authenticate Payer operation.

Initiate Authentication Request

You can initiate authentication by providing the following fields in the Initiate Authentication request:

Parameter Existence Description
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token Required Details of the card being used for the payment.
Note that you can also use network tokens and device payment tokens as source of funds in payer authentication. For more information, see FAQs.
order.currency Required The currency of the order.
transaction.id Required A unique identifier for this payment authentication.
order.id Required A unique identifier for this order.
authentication.channel Required The channel in which the authentication request is being initiated. You can specify one of the following:
  • MERCHANT_REQUESTED: If you are requesting authentication of a cardholder without the payer being available for interaction (for example, as part of processing of a recurring payment). This option is currently not supported.
  • PAYER_BROWSER: If the payer is interacting via web browser (for example, with the merchant's ecommerce web-site).
authentication.purpose Optional

By default, this field is set to "PAYMENT_TRANSACTION" to indicate that authentication is to be performed when processing a card payment. However, you can specify a different purpose to indicate non-payment authentication. See Submit a Non-Payment Authentication Request.

.
authentication.acceptVersions Optional The 3DS versions that you will accept for this payment. If you do not specify a version, both 3DS1 and 3DS2 will be accepted. The gateway uses 3DS2 (if supported by the issuer and the card) and falls back to 3DS1 only where 3DS2 is not available. If both are not available, the authentication will not proceed.
order.merchantCategoryCode Optional Provide the Merchant Category Code if you want to override the default value configured on your acquirer link.
To allow any ACS Method call process to complete before you attempt the Authenticate Payer operation, it is recommended that you submit the Initiate Authentication operation at the earliest opportunity in your checkout process, and act on the response immediately. This will typically be when the payer completes entering their card number on the checkout page, for example, 'onBlur' event of the Card Number input field, or when selecting a card from those recorded against their account, if your site has card-on-file capabilities. Allow at least ten seconds for the ACS Method call to complete.
When you submit the Authenticate Payer request before the ACS Method call completes, the gateway returns HTTP 503 response code. If this happens, pause for a few seconds and then resubmit the Authenticate Payer request as-is. Once the method call has been completed, or ten seconds have elapsed, the request will be allowed to proceed.
Initiate Authentication Response

The gateway returns the following key fields in the Initiate Authentication response:

  • authentication.version: If 3DS authentication of the payer is available, this field shows the type 3DS1 or 3DS2. If both are available, 3DS2 is returned.
  • authentication.3ds2.methodSupported: If 3DS2 is available and if the issuer's ACS supports a Method call, this field shows SUPPORTED. The Method call can be used by the ACS to gather additional data prior to the authentication request to increase the likelihood of frictionless authentication being available. The method call is triggered in a hidden iframe, so is invisible to the payer. It also does not provide any callback upon completion.
  • transaction.authenticationStatus: Check out this field if you want more details about the authentication status.
  • response.gatewayRecommendation: This field allows you to determine the next step. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

    response.gatewayRecommendation Next step
    DO_NOT_PROCEED Do not proceed with 3DS authentication for this card, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
    PROCEED You can proceed to authenticate the payer using the Authenticate Payer operation.
  • authentication.redirectHtml: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a hidden DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,
    div.innerHtml= response.authentication.redirectHtml;
     
    eval(document.getElementById('initiate-authentication-script').text)
    	
    If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.
Examples
Initiate Authentication Request
URL https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID>
HTTP Method PUT
{ 
   "authentication":{ 
      "acceptVersions":"3DS1,3DS2",
      "channel":"PAYER_BROWSER",
      "purpose":"PAYMENT_TRANSACTION"
   },
   "correlationId":"test",
   "order":{ 
      "currency":"AUD"
   },
   "sourceOfFunds":{ 
      "provided":{ 
         "card":{ 
            "number":"<card_number>"
         }
      }
   },
   "apiOperation":"INITIATE_AUTHENTICATION"
}
	
Initiate Authentication Response -3DS2
{
   "authentication":{
      "3ds2":{
         "directoryServerId":"A000000004",
         "methodCompleted":false,
         "methodSupported":"SUPPORTED",
         "protocolVersion":"2.1.0",
         "requestorId":"test2ID",
         "requestorName":"test2Name"
      },
      "acceptVersions":"3DS1,3DS2",
      "channel":"PAYER_BROWSER",
      "purpose":"PAYMENT_TRANSACTION",
      "redirect":{
         "customized":{
            "3DS":{
               "methodPostData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5LzIxY2FlYjc1MDIyMGEyMDg0Y2E5MjRkYzhlNTAzYjZhZjIyNDc4NzU5ZjgwODMyMGZmMTZkZDJhZWExNGQyN2MiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9",
               "methodUrl":"<method_url>"
            }
         }
      },
      "redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5LzIxY2FlYjc1MDIyMGEyMDg0Y2E5MjRkYzhlNTAzYjZhZjIyNDc4NzU5ZjgwODMyMGZmMTZkZDJhZWExNGQyN2MiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); e.remove(); } </script> </div>",
      "version":"3DS2"
   },
   "correlationId":"test",
   "merchant":"TEST_3DS2-1",
   "order":{
      "authenticationStatus":"AUTHENTICATION_AVAILABLE",
      "creationTime":"2019-10-28T05:00:27.234Z",
      "currency":"AUD",
      "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "lastUpdatedTime":"2021-04-12T01:29:25.551Z",
      "merchantCategoryCode":"1234",
      "status":"AUTHENTICATION_INITIATED",
      "totalAuthorizedAmount":0,
      "totalCapturedAmount":0,
      "totalRefundedAmount":0
   },
   "response":{
      "gatewayCode":"AUTHENTICATION_IN_PROGRESS",
      "gatewayRecommendation":"PROCEED"
   },
   "result":"SUCCESS",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "number":"512345xxxxxx0008",
            "scheme":"MASTERCARD"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-12T01:29:25.551Z",
   "timeOfRecord":"2019-10-28T05:00:27.234Z",
   "transaction":{
      "amount":0,
      "authenticationStatus":"AUTHENTICATION_AVAILABLE",
      "currency":"AUD",
      "id":"42090084",
      "type":"AUTHENTICATION"
   },
   "version":"60"
}
Initiate Authentication Response (3DS1 Fallback)
{
   "authentication":{
      "3ds1":{
         "veResEnrolled":"Y"
      },
      "acceptVersions":"3DS1,3DS2",
      "channel":"PAYER_BROWSER",
      "purpose":"PAYMENT_TRANSACTION",
      "redirect":{
         "customized":{
            "3DS":{
               "methodPostData":"e30=",
               "methodUrl":"<method_url>"
            }
         }
      },
      "redirectHtml":"<script id=\"initiate-authentication-script\"></script>",
      "version":"3DS1"
   },
   "correlationId":"test",
   "merchant":"TEST_3DS2-1",
   "order":{
      "authenticationStatus":"AUTHENTICATION_AVAILABLE",
      "creationTime":"2021-04-13T02:52:24.532Z",
      "currency":"AUD",
      "id":"3bdbe65b-d0db-4a7d-a8a1-59ae3723da77",
      "lastUpdatedTime":"2021-04-12T01:40:40.317Z",
      "merchantCategoryCode":"1234",
      "status":"AUTHENTICATION_INITIATED",
      "totalAuthorizedAmount":0,
      "totalCapturedAmount":0,
      "totalRefundedAmount":0
   },
   "response":{
      "gatewayCode":"AUTHENTICATION_IN_PROGRESS",
      "gatewayRecommendation":"PROCEED"
   },
   "result":"SUCCESS",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "number":"512345xxxxxx8246",
            "scheme":"MASTERCARD"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-12T01:40:40.317Z",
   "timeOfRecord":"2021-04-13T02:52:24.532Z",
   "transaction":{
      "amount":0,
      "authenticationStatus":"AUTHENTICATION_AVAILABLE",
      "currency":"AUD",
      "id":"2e1d",
      "type":"AUTHENTICATION"
   },
   "version":"60"
}

Step 2: Authenticate Payer

Where the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), and once all payer and payment data has been gathered, you can submit the Authenticate Payer request. You should invoke this when the payer clicks the "Pay Now" button on the checkout page.

Use the same API version as the Initiate Authentication request for the Authenticate Payer request.
Authenticate Payer Request

Submit this operation by providing the following fields.  If you only support 3DS1, the gateway ignores the fields specific to 3DS2. 

Parameter Existence Description
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token Required Details of the card being used for the payment.
order.amount Required The total amount of the order.
transaction.id Required The same transaction.id as the Initiate Authentication operation that preceded it.
order.id Required The same order.id as the Initiate Authentication operation that preceded it.
authentication.redirectResponseUrl Optional The URL to which you want to redirect the payer after completing the payer authentication process. You must provide this URL, unless you are certain that there will be no interaction with the payer.
order.merchantCategoryCode Optional If you do not provide a value, the default configured on your merchant profile will be used.
device.browser Optional Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER.
device.ipAddress Optional Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER, but with provision to exclude where necessary to comply with local legislation.
device.browserDetails parameter group Optional Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER.
billing.address parameter group Optional Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available.
shipping.address parameter group Optional Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available.
customer parameter group Optional Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available.
Authenticate Payer Response

The gateway returns the following key fields in the Authenticate Payer response:

  • transaction.authenticationStatus: Check out this field if you want more details about the authentication status.
  • response.gatewayRecommendation: This field allows you to determine whether you should proceed to a financial transaction or not. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

    response.gatewayRecommendation Next step
    DO_NOT_PROCEED Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
    PROCEED You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow).
  • authentication.redirectHtml: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,
    div.innerHtml= response.authentication.redirectHtml;
     
    eval(document.getElementById('authenticate-payer-script').text)
    	
    If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.

Frictionless Flow

This will redirect the payer’s browser straight back to your website. You can proceed to submit a subsequent payment to the gateway. The gateway will obtain the authentication data related to the payment and will ensure that payments will only be processed where all the 3DS transaction filtering rules (configured by you or your payment service provider) have passed.

Challenge Flow

This will redirect the payer’s browser to the ACS where the issuer’s challenge UI will be presented, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.

  • order.id
  • transaction.id
  • response.gatewayRecommendation
  • result

You can determine the authentication outcome using the value returned in the response.gatewayRecommendation field. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

If you want additional response data, you can use the Retrieve Transaction operation.

response.gatewayRecommendation Next step
DO_NOT_PROCEED Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
PROCEED You can proceed with the payment as authentication is granted.
Authenticate Payer Response Fields

The fields returned in the Authentication Payer response depend on the flow in effect (frictionless vs challenge), how the authentication request was initiated (authentication.channel), and the authentication mechanism for the request (session or certificate or password).

The following fields are returned for a certificate/password authenticated request. For a session-authenticated operation, the response is filtered to remove data that's not related to the payer and only whitelisted fields are returned. For more information, see session-authentication.

* where applicable, based on the 3DS version and flow (frictionless vs challenge) in effect.
Response Field Merchant-authenticated
authentication.method Yes
authentication.3ds.authenticationToken *
authentication.3ds.acsEci Yes
authentication.3ds.transactionId Yes
authentication.3ds2.transactionStatus *
authentication.3ds2.acsTransactionId *
authentication.3ds2.dsTransactionId *
authentication.3ds2.3dsServerTransactionId *
authentication.3ds2.3dsServerTransactionId *
authentication.3ds2.protocolVersion *
authentication.3ds1.veResEnrolled *
authentication.redirectHtml Yes
response.gatewayRecommendation Yes
transaction.type Yes
version Yes
timeOfRecord Yes
result Yes
response.debugInformation *
Examples
Authenticate Payer Request
URL https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID>
HTTP Method PUT
{
  "authentication":{
    "redirectResponseUrl":"<host>/merchantSimulator/jsp/simple/output.jsp"
  },
  "correlationId":"test",
  "device": {
    "browser": "MOZILLA",
    "browserDetails": {
      "3DSecureChallengeWindowSize": "FULL_SCREEN",
      "acceptHeaders": "application/json",
      "colorDepth": 24,
      "javaEnabled": true,
      "language": "en-US",
      "screenHeight": 640,
      "screenWidth": 480,
      "timeZone": 273
    },
    "ipAddress": "127.0.0.1"
   },
   "order":{
      "amount":"100",
      "currency":"AUD"
   },
   "sourceOfFunds":{ 
        "provided":{ 
            "card":{ 
                "number":"<card_number>",
                "expiry":{
                    "month":"1",
                    "year":"39"
                }
            }
        }
    },
  "apiOperation": "AUTHENTICATE_PAYER"
}
	
Authenticate Payer Response - 3DS2 Challenge Flow
{
   "authentication":{
      "3ds":{
         "transactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91"
      },
      "3ds2":{
         "3dsServerTransactionId":"8c4a911c-289a-46c2-a615-887e1cc01a6a",
         "acsTransactionId":"2a8234c9-e8ac-449d-a693-97a113b491fc",
         "directoryServerId":"A000000004",
         "dsTransactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91",
         "methodCompleted":false,
         "methodSupported":"SUPPORTED",
         "protocolVersion":"2.1.0",
         "requestorId":"test2ID",
         "requestorName":"test2Name",
         "transactionStatus":"C"
      },
      "method":"OUT_OF_BAND",
      "payerInteraction":"REQUIRED",
      "redirect":{
         "customized":{
            "3DS":{
               "acsUrl":"https://<host_name>/acs/v2/prompt",
               "cReq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9"
            }
         },
         "domainName":"<domain_name>"
      },
      "redirectHtml":"<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); e.remove(); } </script> </div>",
      "version":"3DS2"
   },
   "correlationId":"test",
   "device":{
      "browser":"MOZILLA",
      "ipAddress":"127.0.0.1"
   },
   "merchant":"TEST_3DS2-1",
   "order":{
      "amount":100,
      "authenticationStatus":"AUTHENTICATION_PENDING",
      "creationTime":"2021-04-13T02:22:59.113Z",
      "currency":"AUD",
      "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "lastUpdatedTime":"2021-04-13T02:44:07.161Z",
      "merchantCategoryCode":"1234",
      "status":"AUTHENTICATION_INITIATED",
      "totalAuthorizedAmount":0,
      "totalCapturedAmount":0,
      "totalRefundedAmount":0,
      "valueTransfer":{
         "accountType":"NOT_A_TRANSFER"
      }
   },
   "response":{
      "gatewayCode":"PENDING",
      "gatewayRecommendation":"PROCEED"
   },
   "result":"PENDING",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "expiry":{
               "month":"1",
               "year":"39"
            },
            "number":"512345xxxxxx0008",
            "scheme":"MASTERCARD"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-13T02:44:07.161Z",
   "timeOfRecord":"2021-04-13T02:22:59.113Z",
   "transaction":{
      "acquirer":{
         "merchantId":"99554411"
      },
      "amount":100,
      "authenticationStatus":"AUTHENTICATION_PENDING",
      "currency":"AUD",
      "id":"42090084",
      "type":"AUTHENTICATION"
   },
   "version":"60"
}
Authenticate Payer Response - 3DS1 Fallback
{
   "authentication":{
      "3ds1":{
         "veResEnrolled":"Y"
      },
      "payerInteraction":"REQUIRED",
      "redirect":{
         "domainName":"<domain_name>"
      },
      "redirectHtml":"<div id=\"redirectTo3ds1AcsSimple\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"redirectTo3ds1Frame\" name=\"redirectTo3ds1Frame\" height=\"100%\" width=\"100%\" > </iframe> <form id =\"redirectTo3ds1Form\" method=\"POST\" action=\"https://<host_name>/acs/b6594e88-608f-4897-a8b5-dd491dc1e54d\" target=\"redirectTo3ds1Frame\"> <input type=\"hidden\" name=\"PaReq\" value=\"eAFVUd9vgjAQfjfxfyBkr6OlgENz1uDUaBadmZr9eFlYaYRFwNEi7r9fizC3e7rvu97Xu+9gdE4PxokXIsmzoWlb2DR4xvIoyfZDc7ed3frmiHY7sI0LzicbzsqCU1hyIcI9N5JI9XiuT8hdz6SwDp74F4VGjio1iwBqoeoqWBxmkkLIvsaLFbWbANQQkPJiMaGSCwnokkMWppxulo8P03dnslF6NQEsLzNZfFPs9AC1AMriQGMpjwOEqqqyRJrIWFgsTwHpEqDrDOtSTyPUNuckovPpYo484o53n1XwHK9Orx9sFvRexFs+BKRfQBRKTgm2+9gnvoGdgY0H2AVU8xCmeiAa7CbGjY2xhbHa6sLBUX8VXICq6dJfCpSphXK9XaZFwM/HPONKVW39mwO6Tn4/114yqTzzbOK4Xr8On7jKlKagVRJlFLGxV8toAEi3ouZgypX6nor5d+du5wf/BK8K\" /> <input type=\"hidden\" name=\"TermUrl\" value=\"https://<host_name>/callbackInterface/gateway/e91c0cc18c143f205a081cde25a3a8cec28b04bb90169115295beb29d0c1dc28\" /> <input type=\"hidden\" name=\"MD\" value=\"\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectTo3ds1Form\"); if (e) { e.submit(); e.remove(); } </script> </div>",
      "version":"3DS1"
   },
   "correlationId":"test",
   "device":{
      "browser":"MOZILLA",
      "ipAddress":"127.0.0.1"
   },
   "merchant":"TEST_3DS2-1",
   "order":{
      "amount":100,
      "authenticationStatus":"AUTHENTICATION_PENDING",
      "creationTime":"2021-04-13T02:52:24.532Z",
      "currency":"AUD",
      "id":"3bdbe65b-d0db-4a7d-a8a1-59ae3723da77",
      "merchantCategoryCode":"1234",
      "status":"AUTHENTICATION_INITIATED",
      "totalAuthorizedAmount":0,
      "totalCapturedAmount":0,
      "totalRefundedAmount":0,
      "valueTransfer":{
         "accountType":"NOT_A_TRANSFER"
      }
   },
   "response":{
      "gatewayCode":"PENDING",
      "gatewayRecommendation":"PROCEED"
   },
   "result":"PENDING",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "expiry":{
               "month":"1",
               "year":"39"
            },
            "number":"512345xxxxxx8246",
            "scheme":"MASTERCARD"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-13T02:54:19.182Z",
   "timeOfRecord":"2021-04-13T02:52:24.532Z",
   "transaction":{
      "acquirer":{
         "merchantId":"99554411"
      },
      "amount":100,
      "authenticationStatus":"AUTHENTICATION_PENDING",
      "currency":"AUD",
      "id":"three",
      "type":"AUTHENTICATION"
   },
   "version":"60"
}

Step 3: Use the Authentication Result in a Payment Operation

When the result of the Authenticate Payer operation indicates that you can proceed with the payment (response.gatewayRecommendation=PROCEED), you may initiate an Authorize or Pay operation. In addition to the standard fields, you must provide the following fields:

  • order.id: Provide the order.id that you supplied in the Initiate Authentication and Authenticate Payer operations.
  • authentication.transactionId: Provide the transaction.id that you supplied in the Initiate Authentication and Authenticate Payer operations. You do not need to include any of the fields in the authentication parameter group, as the gateway will use the authentication.transactionId to look up the authentication results that it stored when you asked it to perform authentication. The gateway will pass the required information to the acquirer.
Examples
Pay Request
URL https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID>
HTTP Method PUT
 
{
    "apiOperation":"PAY",
    "authentication":{
        "transactionId":"<your_transaction_ID>"
    },
    "order":{
        "amount":"100",
        "currency":"AUD",
        "reference":"<your_order_ID>"
    },
    "sourceOfFunds":{
        "provided":{ 
            "card":{ 
                "number":"<card_number>",
                "expiry":{
                    "month":"1",
                    "year":"39"
                }
            }
        },
        "type":"CARD"
    },
    "transaction":{
        "reference":"<your_order_ID>"
    }
}
	
Pay Response - 3DS2
{
   "authentication":{
      "3ds":{
         "acsEci":"02",
         "authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
         "transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af"
      },
      "3ds2":{
         "dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af",
         "protocolVersion":"2.1.0",
         "transactionStatus":"Y"
      },
      "transactionId":"249213216",
      "version":"3DS2"
   },
   "authorizationResponse":{
      "posData":"1605S0100130",
      "transactionIdentifier":"TidTest"
   },
   "device":{
      "browser":"MOZILLA",
      "ipAddress":"127.0.0.1"
   },
   "gatewayEntryPoint":"WEB_SERVICES_API",
   "merchant":"TEST_3DS2-1",
   "order":{
      "amount":100.00,
      "authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
      "chargeback":{
         "amount":0,
         "currency":"AUD"
      },
      "creationTime":"2021-04-13T02:11:06.102Z",
      "currency":"AUD",
      "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "lastUpdatedTime":"2021-04-13T02:11:57.049Z",
      "merchantAmount":100.00,
      "merchantCategoryCode":"1234",
      "merchantCurrency":"AUD",
      "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "status":"CAPTURED",
      "totalAuthorizedAmount":100.00,
      "totalCapturedAmount":100.00,
      "totalRefundedAmount":0.00
   },
   "response":{
      "acquirerCode":"00",
      "gatewayCode":"APPROVED"
   },
   "result":"SUCCESS",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "brand":"MASTERCARD",
            "expiry":{
               "month":"1",
               "year":"39"
            },
            "fundingMethod":"CREDIT",
            "issuer":"<issuer>",
            "number":"512345xxxxxx0008",
            "scheme":"Mastercard",
            "storedOnFile":"NOT_STORED"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-13T02:11:57.049Z",
   "timeOfRecord":"2021-04-13T02:11:56.973Z",
   "transaction":{
      "acquirer":{
         "batch":1,
         "id":"<acquirer_id>",
         "merchantId":"99554411"
      },
      "amount":100.00,
      "authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
      "authorizationCode":"028941",
      "currency":"AUD",
      "id":"1",
      "receipt":"1908266016",
      "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "source":"INTERNET",
      "stan":"496",
      "terminal":"1234",
      "type":"PAYMENT"
   },
   "version":"60"
}
Pay Response - 3DS1 Fallback
{
   "authentication":{
      "3ds":{
         "acsEci":"02",
         "authenticationToken":"jHyn+7YFi1EUAREAAAAvNUe6Hv8=",
         "transactionId":"3nzQOuTJDVOsRLuDT9V671B8QkU="
      },
      "3ds1":{
         "paResStatus":"Y",
         "veResEnrolled":"Y"
      },
      "transactionId":"5791",
      "version":"3DS1"
   },
   "authorizationResponse":{
      "posData":"1605S0100130",
      "transactionIdentifier":"TidTest"
   },
   "device":{
      "browser":"MOZILLA",
      "ipAddress":"127.0.0.1"
   },
   "gatewayEntryPoint":"WEB_SERVICES_API",
   "merchant":"TEST_3DS2-1",
   "order":{
      "amount":100.00,
      "authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
      "chargeback":{
         "amount":0,
         "currency":"AUD"
      },
      "creationTime":"2021-04-13T03:17:44.895Z",
      "currency":"AUD",
      "id":"f808076a-0bc6-4f1b-8100-cfe46e43676e",
      "lastUpdatedTime":"2021-04-13T03:19:45.964Z",
      "merchantAmount":100.00,
      "merchantCategoryCode":"1234",
      "merchantCurrency":"AUD",
      "reference":"9b57808a-474e-445d-b2ca-09d571f5ea75",
      "status":"CAPTURED",
      "totalAuthorizedAmount":100.00,
      "totalCapturedAmount":100.00,
      "totalRefundedAmount":0.00
   },
   "response":{
      "acquirerCode":"00",
      "gatewayCode":"APPROVED"
   },
   "result":"SUCCESS",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "brand":"MASTERCARD",
            "expiry":{
               "month":"1",
               "year":"39"
            },
            "fundingMethod":"CREDIT",
            "issuer":"<issuer>",
            "number":"512345xxxxxx8246",
            "scheme":"Mastercard",
            "storedOnFile":"NOT_STORED"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-13T03:19:45.964Z",
   "timeOfRecord":"2021-04-13T03:19:45.703Z",
   "transaction":{
      "acquirer":{
         "batch":1,
         "id":"<acquirer_id>",
         "merchantId":"99554411"
      },
      "amount":100.00,
      "authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
      "authorizationCode":"003879",
      "currency":"AUD",
      "id":"1",
      "receipt":"1908286018",
      "reference":"9b57808a-474e-445d-b2ca-09d571f5ea75",
      "source":"INTERNET",
      "stan":"499",
      "terminal":"1234",
      "type":"PAYMENT"
   },
   "version":"60"
}

Other Options

Retrieve 3DS Authentication Results

If you wish to retrieve the authentication results at any stage, use the Retrieve Transaction operation. Note that fields that are only used during the authentication, for example, authentication.redirectHtml, are not persisted in the gateway hence not returned.

Submit a Pre-Authenticated Payment Request

If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in the authentication parameter group of the Authorize or Pay operation.

All fields are optional, as whether or not they were provided to you by the external 3DS MPI depends on the authentication version (3DS1 or 3DS2) and the status of the transaction. However, if you have the data it's recommended that you provide it.

  • authentication.3ds.acsEci: The Electronic Commerce Indicator that may be returned to you in the authentication response message.
  • authentication.3ds.authenticationToken: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.
  • authentication.3ds.transactionId: A unique transaction identifier generated by the gateway for the 3DS authentication.
    For 3DS1, this field corresponds to XID, which is an identifier generated by the gateway on behalf of the merchant. An XID submitted in this field must be in base64 format.
    For 3DS2, this field corresponds to the identifier assigned by the scheme directory server.
  • authentication.3ds1.paResStatus: Indicates the result of payer authentication with the issuer.
  • authentication.3ds1.veResEnrolled: Indicates whether or not payer authentication is available for the card number you provided.
  • authentication.3ds2.protocolVersion: The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo. For example, 2.1.0
  • authentication.3ds2.transactionStatus: Indicates the result of payer authentication with the issuer.
  • authentication.3ds2.statusReasonCode: A code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus. You must provide this when authentication.3ds2.transactionStatus returns N, U, or R.
Mastercard/Visa require that if you are using Mastercard SecureCode/Verified by Visa, and if the authentication was attempted, you must provide authentication.3ds.authenticationToken.
Submit a Non-Payment Authentication Request

If you want to perform authentication to only verify the identity of the payer without proceeding to the payment, you must indicate the authentication purpose in the Initiate Authentication request. For example, you may want to authenticate the payer when the payer enters their card details for later use during customer registration or account creation on your website. The ability to complete the authentication process in a non-payment environment enhances payer experience and reduces payer drop-off rates.

The authentication details from a non-payment authentication cannot be used to claim chargeback liability in a payment transaction. If you provide the authentication details in a payment transaction, the gateway rejects the request.

To perform a non-payment authentication, provide the following fields in the Initiate Authentication request:

  • order.currency: Any currency supported on your acquirer link(s).
  • authentication.purpose: Indicates the context in which payer authentication is being requested. You can specify one of the following:
    • ADD_CARD: Authentication performed before a payer's card is stored on file either directly by you or using the gateway's tokenization feature. A payment is not being processed.
    • MAINTAIN_CARD: Authentication performed before updating details of a payer's card stored on file either directly by you or using the gateway's tokenization feature. A payment is not being processed.

    If the authentication scheme does not support the purpose you have requested, the gateway returns AUTHENTICATION_NOT_SUPPORTED in the response. Note that by default the gateway sets this field to PAYMENT_TRANSACTION to allow the authentication to be used for a payment transaction.

Advanced Payment Session Integrations

If you have used a payment session (session Id) to store the authentication details, the POST request submitted by the payer’s browser to your website on completion of the Authenticate Payer request will be parameterised allowing you to determine the authentication outcome. The individual authentication parameters, for example, authentication.3ds2.transactionStatus.data, may be useful in an advanced integration or if you have the need to provide the authentication data in a payment processed via another gateway. To do this, you can submit a Retrieve Transaction request or choose to decrypt the encrypted authentication data (see the following steps):

  1. Create a session using the Create Session operation.
  2. Add relevant data to the session Id (returned in the Create Session response) using the Update Session request.
  3. Use this session Id in the Initiate Authentication and Authenticate Payer requests.
  4. The redirect of the payer's browser to your website will contain payer authentication details in the encryptedData field. It is an encrypted JSON object containing the authentication data obtained during the authentication process. It contains the following fields:
    • encryptedData.ciphertext
      • authentication.3ds.acsEci
      • authentication.3ds.authenticationToken
      • authentication.3ds.transactionId
      • authentication.3ds1.veResEnrolled
      • authentication.3ds1.paResStatus
      • authentication.3ds2.transactionStatus
      • authentication.3ds2.dsTransactionId
      • transaction.authenticationStatus
      • authentication.3ds2.statusReasonCode
      • sourceOfFunds.provided.card.number
      • sourceOfFunds.provided.card.expiry.month
      • sourceOfFunds.provided.card.expiry.year
      • sourceOfFunds.token
      • order.id
      • transaction.id
    • encryptedData.nonce
    • encryptedData.tag
  5. To decrypt the content returned in the encryptedData.ciphertext field, use the session.aes256Key (returned in the Create Session response) in the GCM mode. The Base64 encoded key is a secret and must be known only by you.
public final class SessionDataDecrypter {
    /**
     * The algorithm used for encryption/decryption
     */
    private static final String SYMMETRIC_ALGORITHM = "AES/GCM/NoPadding";
  
    /**
     * The algorithm to be associated with the secret key material
     */
    private static final String SYMMETRIC_KEY_TYPE = "AES";
  
    /**
     * The secret key associated with the session, as returned in the session.aes256Key in a Create Session response.
     */
    private final byte[] key;
  
    /**
     * Constructs a new object with the given key. The key is Base64 encoded, as returned in the session.aes256Key
     * field in a Create Session response. This key must be kept secret, as it may be used to encrypt, decrypt and
     * authenticate data for that session.
     *
     * @param encodedKey Key to be used for decryption.
     */
    public SessionDataDecrypter(String encodedKey) {
        key = Base64.getDecoder().decode(encodedKey);
    }
  
    /**
     * Performs decryption of the given ciphertext, using the key passed in the constructor and the associated nonce.
     * The tag is used to authenticate the ciphertext.
     *
     * @param ciphertext Encrypted and authenticated session data
     * @param nonce Nonce/Initialization vector associated with the ciphertext
     * @param tag Authentication tag
     * @return The decrypted session data
     * @throws AEADBadTagException if the data cannot be authenticated with the given tag
     * @throws InvalidKeyException if the key cannot be constructed properly. This may indicate that it has not been
     * correctly retrieved from the response field
     * @throws GeneralSecurityException other than {@link AEADBadTagException} and {@link InvalidKeyException}, should
     * not be thrown in a correctly set up environment
     */
    public String decrypt(String ciphertext, String nonce, String tag)
            throws GeneralSecurityException {
        Key keySpec = new SecretKeySpec(key, SYMMETRIC_KEY_TYPE);
  
        // The Java crypto classes expect the ciphertext and tag to be a single input, so they need to be concatenated
        byte[] encryptedBytes = Base64.getDecoder().decode(ciphertext);
        byte[] tagBytes = Base64.getDecoder().decode(tag);
        byte[] input = new byte[encryptedBytes.length + tagBytes.length];
        System.arraycopy(encryptedBytes, 0, input, 0, encryptedBytes.length);
        System.arraycopy(tagBytes, 0, input, encryptedBytes.length, tagBytes.length);
  
        // Configure the cipher with AES, using GCM parameter specifying the nonce/initialization vector
        byte[] iv = Base64.getDecoder().decode(nonce);
        GCMParameterSpec parameterSpec = new GCMParameterSpec(tagBytes.length * Byte.SIZE, iv);
        final Cipher decrypter = Cipher.getInstance(SYMMETRIC_ALGORITHM);
        decrypter.init(Cipher.DECRYPT_MODE, keySpec, parameterSpec);
  
        // Perform the decryption and return the value.
        byte[] decryptedBytes = decrypter.doFinal(input);
        return new String(decryptedBytes, StandardCharsets.UTF_8);
    }
}
	
Using 3DS as an Aggregator Merchant

Aggregator merchants can enable their sub-merchants to use the Authentication API on the gateway. The sub-merchants are not required to have a contractual relationship with the acquirer nor with the gateway. The aggregator merchant can submit the sub-merchant details required for initiating the authentication via the Initiate Authentication operation. For more information, see Aggregator Support.

FAQs

Can I use the Authentication API as a client-side API?

You can use the Authentication API as a server-side or a client-side API.

  • Client-side API: You must first establish the authentication channel where your merchant server must communicate with the gateway server for creating the session on the gateway. Once the session is created, you can use it to authenticate all the subsequent API operations needed for managing the 3DS integration flows directly from the browser using the 3DS JavaScript API or using your own library.
  • Server-side API: You must perform all the operations needed for managing the 3DS integration flows directly from your merchant server to the gateway server. You can support all authentication transaction modes via the Authentication API.
    • Authentication Only: Perform Initiate Authentication and Authenticate Payer.
    • Authentication and Payment Transaction: Perform Initiate Authentication, Authenticate Payer, and Authorize/Pay.
    • Pre-authenticated Payment Transaction: Perform Authorize/Pay using authentication details from an external provider.
How are 3-D Secure interactions represented on the gateway?

The Authentication API records the details of the payer authentication using 3DS1 or 3DS2 as a separate AUTHENTICATION transaction on the order.

When you retrieve an order using the Retrieve Order operation or receive a Reporting API response, it may contain an additional AUTHENTICATION transaction. Also, when you use Webhook Notifications, you may receive an additional notification for the AUTHENTICATION transaction.

For details about AUTHENTICATION transactions please refer to the list of response parameters for the Authenticate Payer operation.

Can I use network tokens as source of funds in payer authentication?

You can use network tokens for payer authentication from API v55 onwards. The Suncorp Gateway currently supports processing network tokens obtained from the following tokenization service providers: Mastercard Digital Enablement Service (MDES), Visa Token Service (VTS).

If you have obtained a network token by integrating directly to the network tokenization service provider, then you must supply token details using the following fields:

  • sourceOfFunds.type=SCHEME_TOKEN: Enables the gateway to identify the source of fund provided in the request as a network token. MDES and VTS are supported from API v51 and v53 respectively.
  • sourceOfFunds.provided.card.number: The network token. Supply the value for the MDES "Token PAN" or the VTS "Token".
  • sourceOfFunds.provided.card.expiry: (optional) The network token expiry.

If you have been enabled for network tokenization by your payment service provider, any request to the gateway for a gateway token will also attempt to generate a corresponding network token for enabled schemes, where supported by the card issuer. The gateway will also attempt network tokenization for any applicable cards already stored in the gateway token repository. The Initiate Authentication request will use the network token if available else the Funding PAN (FPAN) stored against the gateway token will be used. This model currently only supports MDES tokens.

Can I use device payment tokens as source of funds in payer authentication?

You can use device payment tokens for payer authentication, from API v55 onwards. Only payment tokens obtained from Google Pay SDK are supported. You can provide an encrypted payment token or the "pan" obtained from a decrypted payment token for payer authentication. The gateway only accepts authentication requests with FPAN, requests with DPANs will be rejected. To supply card details via payment token, provide the following field:

  • order.walletProvider=GOOGLE_PAY
  • sourceOfFunds.provided.card.devicePayment.paymentToken: Applicable only if payment token is decrypted by the gateway. It's the encrypted payment token obtained from the Google Pay SDK.
  • sourceOfFunds.provided.card.number: Applicable only if payment token is decrypted by you. The value corresponding to the Google Pay JSON Key "pan".
What can I do to increase the chances of frictionless flow?

The Authenticate Payer request can take a large volume of information about the payer and the transaction. For example, you can provide the following data in the request using the fields in the customer.account parameter group, which helps the issuer's ACS to assess the level of risk associated with the activity. This means in the case of legitimate payments it helps the ACS to confirm that the payer is likely to be the actual cardholder.

  • Is the payer using an existing account?
    • customer.account.history.creationDate
  • How long has the account existed?
    • customer.account.history.lastUpdated
    • customer.account.history.passwordLastChanged
  • How frequently has the payer shopped with you?
    • customer.account.history.addCardAttempts
    • customer.account.history.annualActivity
    • customer.account.history.recentActivity
    • customer.account.history.shippingAddressDate
  • Have they ordered these items from you previously?
    • customer.account.history.issuerAuthentication.acsTransactionId
    • customer.account.history.issuerAuthentication.time
    • customer.account.history.issuerAuthentication.type
  • Have you observed suspicious activity (e.g. failed login attempts) on the account?
    • customer.account.history.suspiciousActivity
    • customer.account.authentication.method
    • customer.account.authentication.time

You can also provide the following recommended fields for each card scheme in the Authenticate Payer request. Note that this list is not definitive and may be subject to change.

Field Mastercard Visa American Express Notes
shipping.contact.email - - Y Required to calculate merchant risk
shipping.method - - Y Required to calculate merchant risk
order.valueTransfer.amount - - Y Required to calculate merchant risk. Applicable only to gift cards.
order.valueTransfer.numberOfCards - - Y Required to calculate merchant risk. Applicable only to gift cards.
order.valueTransfer.currency - - Y Required to calculate merchant risk. Applicable only to gift cards.
order.supply.preorderAvailabilityDate - - Y Required to calculate merchant risk
order.supply.preorder - - Y Required to calculate merchant risk
order.supply.reorder - - Y Required to calculate merchant risk
order.valueTransfer.accountType - Y - Required by Visa and by other schemes in certain markets (e.g. Brazil). Not applicable if order.valueTransfer.accountType=NOT_A_TRANSFER
It is recommended that you supply as much of this data as possible, as this increases the likelihood that the ACS will offer frictionless authentication, which greatly improves the payer experience resulting in a more streamlined checkout.
How do I determine the authentication status?

The gateway provides the authentication status in the transaction.authenticationStatus field. This field may return one of the following values depending on the authentication stage:

  • AUTHENTICATION_ATTEMPTED: Payer authentication was attempted and a proof of authentication attempt was obtained.
  • AUTHENTICATION_AVAILABLE: Payer authentication is available for the payment method provided.
  • AUTHENTICATION_FAILED: The payer was not authenticated. You should not proceed with this transaction.
  • AUTHENTICATION_NOT_SUPPORTED: The requested authentication method is not supported for this payment method.
  • AUTHENTICATION_NOT_IN_EFFECT: There is no authentication information associated with this transaction.
  • AUTHENTICATION_PENDING: Payer authentication is pending completion of a challenge process.
  • AUTHENTICATION_REJECTED: The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.
  • AUTHENTICATION_REQUIRED: Payer authentication is required for this payment, but was not provided.
  • AUTHENTICATION_SUCCESSFUL: The payer was successfully authenticated.
  • AUTHENTICATION_UNAVAILABLE: The payer was not able to be authenticated due to a technical or other issue.
How do I view authentication details in the Merchant Administration portal?

You can view authentication details for both individual authentications and authentications that proceeded with the payment in the Merchant Administration portal. Search for the order or transaction in the search page and view the authentication details.

If you want to view authentication details for a 3DS1 authentication, for example, to view data for fields such as PARes, PAReq, then use the Authentications search option in the Merchant Administration portal.

Yes, you can bypass 3DS authentication for payers where payments are deemed low risk by the external risk provider. For more information, see Dynamic 3DS.

Test Your Integration

You can test your integration for 3DS Authentication via the gateway by using the 3DS Emulator. To access the emulator, use your test merchant profile (type "TEST" as a prefix to the Merchant ID supplied by your payment service provider).

The test cards provide a range of gateway results for the various 3DS scenarios but do not necessarily emulate ACS behavior.

Testing is supported for the following 3DS schemes:

  • Mastercard SecureCode
  • Verified by Visa, and
  • American Express
Details

To test 3DS functionality:

  1. Use a test card (from the following table) when submitting the Initiate Authentication request for your TEST merchant profile.
  2. Use the expiry code "01/39" to get a successful authorization/payment in an end-to-end testing flow. Please note that the card(s) listed with * will not work for subsequent authorizations or payments.
  3. Check that the authentication is available (authentication.version=3DS2 or 3DS1)
  4. Submit an Authenticate Payer request and insert content of the authentication.redirectHtml field into the page displayed to the payer to redirect the payer's browser to the 3DS Emulator challenge page.
    The 3DS Emulator redirects the payer's browser back to your website once the authentication is complete.
  5. Select a specific 3DS authentication result via drop-down selection in the 3DS Emulator (see values in the following table).
  6. Use the transaction ID for this 3DS authentication in authentication.transactionId in a subsequent Authorize or Pay transaction request. It should indicate only where authentication is successful and if the card allows for subsequent authorization or payment.
Test Cards Purpose Card Number 3DS1 Enrolled 3DS2 Enrolled Method URL tranStatus tranStatusReason ECI Authentication Token
Mastercard 3DS2 - Challenge (Method URL provided) 5123450000000008
2223000000000007
Yes Yes

Yes

C - - -
3DS2 - Frictionless (Method URL provided) 5123456789012346 Yes Yes Yes Y - 02 mHyn+7YFi1EUAREAAAAvNUe6Hv8=
3DS2 - Frictionless (No Method URL) 5555555555000018* Yes Yes No Y - 02 mHyn+7YFi1EUAREAAAAvNUe6Hv8=
3DS2 - Authentication Attempted 5500005555555559 Yes Yes No A - 01 nHyn+7YFi1EUAREAAAAvNUe6Hv8=
3DS2 - Authentication Rejected 5506900140100503 No Yes No R 04 - -
3DS1 - Not enrolled for 3DS2 resulting in fallback to 3DS1 5506900140100305 Yes No No - - - -
3DS2 - Error during Initiate Authentication operation resulting in Generic Error Response 5210760000000004 Yes Exception - - - - -
3DS2 - Error during Authenticate Payer operation resulting in Generic Error Response 5455031257390496 Yes Yes No Exception - - -
5455031252665454 Yes Yes No Exception - - -
3DS1 & 3DS2 - Not Enrolled Response 5111111111111118 No No - - - - -
2223000000000023 No No - - - - -
3DS2 - Authentication Unavailable Error during Authenticate Payer operation resulting in a response of authenticationStatus = AUTHENTICATION_UNAVAILABLE 5123459999998221 Yes Yes No Recoverable Exception - - -
Visa 3DS2 - Challenge (No Method URL) 4440000009900010  Yes Yes No C - - -
3DS2 - Frictionless (No Method URL) 4440000042200014  Yes Yes Yes Yes - 05 mHyn+7YFi1EUAREAAAAvNUe6Hv8=
3DS2 - Authentication Attempted 4440000042200022  No Yes No A - 06 nHyn+7YFi1EUAREAAAAvNUe6Hv8=
American Express 3DS2 - Challenge (No Method URL) 340000099900051 No Yes No C - - -
3DS2 - Frictionless (Method URL provided) 340353278080900 Yes Yes Yes Yes - 05 mHyn+7YFi1EUAREAAAAvNUe6Hv8=
Discover 3DS1 - Not enrolled for 3DS2 resulting in fallback to 3DS1 6011000991300009 Yes No No - - - -
3DS1 & 3DS2 - Not Enrolled Response 6011640745800505 - No - - - - -
Maestro PSD2 Exemptions and Whitelisted Merchants 5000000000000000005 Yes Yes No No 81 06 kNyn+7YFi1EUAREAAAAvNUe6Hv8=

In the case of a "C" transStatus, the following outcomes are possible via drop-down selection in the 3DS Emulator:

Description transStatus challengeCancel eci
Successful authentication
Y - 05 / 02
Failed authentication
N - 07 / 00
Cancelled authentication
N 01 07 / 00
Unable to authenticate U - 07 / 00
Authentication rejected R - 07 / 00

Copyright © 2022 Suncorp