3D Secure Version 2

Overview

3DSv2 is the latest protocol defined by EMVCo which allows consumers to authenticate with their card issuer when making card-not-present ecommerce purchases. This security layer helps to protect the merchants from fraud.

Merchant collects all the details about the cardholder and sends to the issuer to verify. The liability shift will be depend on the authentication result after the issuer assesses the information provided by the Merchant. There could be two possible scenarios: frictionless flow or challenge flow.

The flow could be frictionless if the issuer can verify the cardholder’s identity based on the provided details. This is the case when the issuer authenticates the cardholder without any interruption in the checkout process.

The issuer can also request the cardholder to go through the Challenge flow to authenticate the cardholder. There is redirection to the issuer in order to get the authentication.

The following process outlines how you can use Bambora’s 3DSecure v2 to carry out authentication and transaction requests for a single payment.

3DSv2 Authentication flows

Frictionless

Flow Summary

Flow Summary

After Merchant calls the 3DS Authentication Request, if the transaction is identified as low risk by the ACS, Merchant will get the Frictionless Authentication Prep response from Bambora. That means the Cardholder completes the authentication process and the Merchant can use the Authentication result to decide whether to continue/ decline processing the transaction.

Sample Frictionless Authentication Prep Response

{
    "transactionReference": "56e6cb5f-d1f4-4d22-b8d3-1384f7b17a62",
    "authenticationSessionId": "4548e709-d145-4d71-b0df-de4255d43383",
    "authenticationPreparationResponse": {
        "authenticationStatus": "Succeeded",
        "cavv": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
        "eci": "05",
        "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
    }
}

Merchant need to use the details from the response in the Payment request (SRAPI)

Frictionless with Method URL

Flow Summary

Flow Summary

Based on the BIN or BIN range, the issuer may decide to use Method URL to collect the device fingerprint from the Cardholder. If the BIN number is in the BIN range that the issuer has defined to request for method URL, Merchant will get the Method URL response from Bambora.

Sample Frictionless with Method URL Authentication Prep Response

{
  "transactionReference": "ca75295b-9d03-4294-9e97-312686884a43",
  "authenticationSessionId": "d886f14b-77c1-42b8-a632-da20d3551f4f",
  "redirectionFormData": {
    "actionUrl": "https://path.to/actionUrl",
	"methodUrl": "https://path.to/methodurl",
    "threeDSMethodData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU3NjRmNjVmLWI4MTYtNDE5Zi05OWU0LWViY2QwNmM0ZTY5MCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL2VzZi1nYXRld2F5LXB1YmxpYy1kZXYuc2VydmljZXMub2dvbmUuc2IuZXUuZ2luZnJhLm5ldC8zZHMtbWV0aG9kLXJlZGlyZWN0aW9uLzcxYjA2MDYxLWViYWUtNDQ2NS05ZTA5LTBiMjlkM2VhZGVlNS9WaXNhL3JlcXVlc3QvY2FsbGJhY2sifQ",
  }
}

Merchant needs to redirect the cardholder to the ActionURL which is provided in the Authentication Prep Response.

The Cardholder is held on the Method URL page and does not require to take any action. When the process is completed, Bambora sends the Authentication Notification to the provided Merchant URL (this URL is provided by Merchant while onboarding).

Sample Authentication Notification

{
 "transactionReference": "3357bd1e-29c1-4f6a-95d4-f1936531511b",
 "authenticationSessionId": "7a96e093-ba49-43b8-8b74-dfd22ff27653",
 "authenticationMode": "MethodUrl_Frictionless",
 "authenticationPreparationResponse": {
  "authenticationStatus": "Succeeded",
  "cavv": "AAABBE****AAA=",
  "eci": "05",
  "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
 },
 "authenticationResponse": "{\"acsReferenceNumber\":\"3DS_LOA_ACS_PPFU_020100_00009\",\"acsTransID\":\"63AEEFE8-BE1F-41FA-AD52-4B5E2E16671D\",\"acsUrl\":\"https://mpi-v2-simulation.test.v-psp.com/acs-simulation/challenge?redirectUrl=https%3A%2F%2Fthreedsv2-api-nuat.bambora.net.au%2Fv1%2Fnotification\",\"cardholderInfo\":\"cardholder\",\"dsTransID\":\"f25084f0-5b16-4c0a-ae5d-b24808a95e4b\",\"Eci\":\"05\",\"transStatus\":\"Y\",\"transStatusReason\":null,\"whiteListStatus\":null,\"challengeCancel\":null,\"messageType\":\"ARes\",\"messageVersion\":\"2.2.0\",\"threeDSServerTransID\":\"73287d8b-4cc3-4bec-9efe-61f2b871a364\"}"
}

Merchant need to use the details from the response in the Payment request (SRAPI).

Challenge

Flow Summary

Flow Summary

Sample Challenge Authentication Prep Response

{
  "transactionReference": "ca75295b-9d03-4294-9e97-312686884a43",
  "authenticationSessionId": "d886f14b-77c1-42b8-a632-da20d3551f4f",
  "redirectionFormData": {
    "actionUrl": "https://path.to/actionUrl",
    "threeDSSessionData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU3NjRmNjVmLWI4MTYtNDE5Zi05OWU0LWViY2QwNmM0ZTY5MCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL2VzZi1nYXRld2F5LXB1YmxpYy1kZXYuc2VydmljZXMub2dvbmUuc2IuZXUuZ2luZnJhLm5ldC8zZHMtbWV0aG9kLXJlZGlyZWN0aW9uLzcxYjA2MDYxLWViYWUtNDQ2NS05ZTA5LTBiMjlkM2VhZGVlNS9WaXNhL3JlcXVlc3QvY2FsbGJhY2sifQ",
    "creq": "eyJhY3NUcmFuc0lEIjoiNUUwRDhFQ0UtNDU0RC00QzkwLTk2QzMtMTRERTZFNTYxNjBFIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1IiwibWVzc2FnZVR5cGUiOiJDUmVxIiwibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiYTQxNzM4ZmUtM2NiNi00NmQzLTk1ZjctODcwNDVlNGRhN2YzIn0"
  },
  "authenticationPreparationResponse": {
    "authenticationStatus": "Required",
    "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
  }
}

Merchant needs to redirect the cardholder to the ActionURL which is provided in the Authentication Prep Response.

The Cardholder is required to take action based on the request on the Challenge page. When the challenge is completed, Bambora sends the Authentication Notification to the provided Merchant URL (this URL is provided by Merchant while onboarding)

Sample Authentication Notification

{
 "transactionReference": "1a5f8c45-0bce-4c8b-b951-4c5f955aff44",
 "authenticationSessionId": "beb17576-0b70-4d65-821b-d923042edfae",
 "authenticationMode": "Challenge",
 "authenticationPreparationResponse": {
  "authenticationStatus": "Succeeded",
  "cavv": "AAABBE****AAA=",
  "eci": "05",
  "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
 },
 "authenticationResponse": "{\"acsReferenceNumber\":\"3DS_LOA_ACS_PPFU_020100_00009\",\"acsTransID\":\"5E0D8ECE-454D-4C90-96C3-14DE6E56160E\",\"acsUrl\":\"https://mpi-v2-simulation.test.v-psp.com/acs-simulation/challenge?redirectUrl=https%3A%2F%2Fthreedsv2-api-nuat.bambora.net.au%2Fv1%2Fnotification\",\"cardholderInfo\":\"cardholder\",\"dsTransID\":\"f25084f0-5b16-4c0a-ae5d-b24808a95e4b\",\"Eci\":null,\"transStatus\":\"C\",\"transStatusReason\":\"16\",\"whiteListStatus\":null,\"challengeCancel\":null,\"messageType\":\"ARes\",\"messageVersion\":\"2.2.0\",\"threeDSServerTransID\":\"557c3c59-df44-4495-87d3-705f6bee1fe9\"}"
}

Merchant need to use the details from the response in the Payment request (SRAPI)

Challenge with Method URL

Flow Summary

Flow Summary

Sample Challenge with Method URL Authentication Prep Response

{
  "transactionReference": "ca75295b-9d03-4294-9e97-312686884a43",
  "authenticationSessionId": "d886f14b-77c1-42b8-a632-da20d3551f4f",
  "redirectionFormData": {
    "actionUrl": "https://path.to/actionUrl",
	"methodUrl": "https://path.to/methodUrl",
    "threeDSMethodData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU3NjRmNjVmLWI4MTYtNDE5Zi05OWU0LWViY2QwNmM0ZTY5MCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL2VzZi1nYXRld2F5LXB1YmxpYy1kZXYuc2VydmljZXMub2dvbmUuc2IuZXUuZ2luZnJhLm5ldC8zZHMtbWV0aG9kLXJlZGlyZWN0aW9uLzcxYjA2MDYxLWViYWUtNDQ2NS05ZTA5LTBiMjlkM2VhZGVlNS9WaXNhL3JlcXVlc3QvY2FsbGJhY2sifQ"
  }
}

Merchant needs to redirect the cardholder to the ActionURL which is provided in the Authentication Prep Response.

Cardholder is required to take challenge based on Issuer’s request. When the action is completed, Bambora sends the Authentication Notification to the provided Merchant URL (this URL is provided by Merchant while onboarding)

Sample Authentication Notification

{
 "transactionReference": "b0437a98-26e5-4e0b-adb0-180d91a9dbad",
 "authenticationSessionId": "8f60ba31-f413-4a97-aa00-308415d9c3a3",
 "authenticationMode": "MethodUrl_Challenge",
 "authenticationPreparationResponse": {
  "authenticationStatus": "Succeeded",
  "cavv": "AAABBE****AAA=",
  "eci": "05",
  "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
 },
 "authenticationResponse": "{\"acsReferenceNumber\":\"3DS_LOA_ACS_PPFU_020100_00009\",\"acsTransID\":\"D1096AB5-22D2-4805-B4EA-ECB53DFC3F91\",\"acsUrl\":\"https://mpi-v2-simulation.test.v-psp.com/acs-simulation/challenge?redirectUrl=https%3A%2F%2Fthreedsv2-api-nuat.bambora.net.au%2Fv1%2Fnotification\",\"cardholderInfo\":\"cardholder\",\"dsTransID\":\"f25084f0-5b16-4c0a-ae5d-b24808a95e4b\",\"Eci\":null,\"transStatus\":\"C\",\"transStatusReason\":\"16\",\"whiteListStatus\":null,\"challengeCancel\":null,\"messageType\":\"ARes\",\"messageVersion\":\"2.2.0\",\"threeDSServerTransID\":\"cf006dee-293b-4323-af4d-390cbfdf1b98\"}"
}

Specification of Authentication messages

3DS Authentication request

In order to start the Authentication, Merchant should be onboarded in the UAT (test) environment. The Merchant can start to send the Authentication preparation request to Bambora. Merchant should include as much information about the transaction and the cardholder as possible as part of authentication.

Merchant will receive the Authentication Preparation Response for their Authentication Preparation request.

UAT API Link

https://threedsv2-api-nuat.bambora.net.au/v1/authentication

Sample of the request

POSThttps://threedsv2-api-nuat.bambora.net.au/v1/authentication

Headers:

Content-Type: application/json

x-api-key: <your API key>

{
    "merchantAccountId": 7,
    "browserInformation": {
        "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
        "ipAddress": "192.168.0.1",
        "javaEnabled": true,
        "javascriptEnabled": true,
        "language": "en-AU",
        "colorDepth": "1bit",
        "screenHeight": 999999,
        "screenWidth": 999999,
        "timeZone": 700,
        "userAgent": "string"
    },
    "card": {
        "pan": "<test card>",
        "cardholderName": "C H Name",
        "expiryDate": {
            "month": 1,
            "year": 2022
        }
    },
    "purchaseInformation": {
        "currency": "AUD",
        "amount": 10,
        "dateTime": "2021-08-12T15:32:48Z"    
    },
    "authenticationInformation": {
        "authenticationIndicator": "PaymentTransaction",
        "messageCategory": "PaymentAuthentication",
        "challengeInformation": {
            "windowSize": "fullscreen"
        }
    },    
    "threeRIIndicator": "RecurringTransaction"
}

Parameters in the request body

Conditions:

• Mandatory: These are the minimum API fields required for a 3DS authentication.

• Recommended: The major card schemes highly recommend including these, as they will enhance the chance of a frictionless flow.

• Optional: These fields are not required for 3DS authentication. The more data the merchant send in the authentication, the better the result of risk assessment is.

• Conditional: These fields must be completed if certain conditions are met.

Authentication Prep Response message

This is the response that Merchant receives from Bambora for their Authentication Preparation Request. Merchant will take next steps based on the Authentication result in the response message.

Parameters in the Response body

Finalise Authentication response

This is the response that the Merchant receives from Bambora after the Cardholder completes the Method URL and Challenge.

Response Code

Parameters in the Response body

Authentication Result

Authentication results are the same for Frictionless and Challenge flows. However it will be provided in a different message.

For Frictionless flow, the Authentication result is provided in the Authentication Preparation Response message.

For Challenge and Method URL flows, the Authentication result is provided in the Finalise Authentication Response message

Authentication Status

For VISA

These are the outcomes of the 3DSv2 Visa Transaction:

For Mastercard

These are the outcome of the 3DSv2 Mastercard Transaction:

Facilitating Redirection for Challenge and MethodURL

Bambora recommends that simple page with an HTML form is built to facilitate a POST request to the action URL returned in the initial response of the 3DSv2 flow, if the result leads to any flow other than Frictionless with no Method URL. The page does not need to display any visual elements to the cardholder but its main purpose is to assist in redirecting. The <form> element will need to have hidden fields whose values which will be obtained from the response of the initial request to Bambora 3DSv2.

It is highly recommended that the page auto-POSTs to its action attribute value upon page loading.

Example code - Frictionless with Method URL and Challenge with Method URL

Response from POST /v1/authentication

{
  "transactionReference": "ca75295b-9d03-4294-9e97-312686884a43",
  "authenticationSessionId": "d886f14b-77c1-42b8-a632-da20d3551f4f",
  "redirectionFormData": {
    "actionUrl": "https://path.to/actionUrl",
	"methodUrl": "https://path.to/methodurl",
    "threeDSMethodData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU3NjRmNjVmLWI4MTYtNDE5Zi05OWU0LWViY2QwNmM0ZTY5MCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL2VzZi1nYXRld2F5LXB1YmxpYy1kZXYuc2VydmljZXMub2dvbmUuc2IuZXUuZ2luZnJhLm5ldC8zZHMtbWV0aG9kLXJlZGlyZWN0aW9uLzcxYjA2MDYxLWViYWUtNDQ2NS05ZTA5LTBiMjlkM2VhZGVlNS9WaXNhL3JlcXVlc3QvY2FsbGJhY2sifQ",
  }
}

HTML Page:

<html>
  <body>
    <form name="EventConfirmRedirection" method="post" action="https://path.to/actionUrl">
      <input type="hidden" value="https://path.to/methodurl" id="methodUrl" name="methodUrl"/>
      <input type="hidden" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6Ijk4OWQ5NzQ4LWQ1NjQtNDk5OS04Mzc0LWM1MmM0ZmMzOTY4ZiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL2VzZi1nYXRld2F5LXB1YmxpYy1kZXYuc2VydmljZXMub2dvbmUuc2IuZXUuZ2luZnJhLm5ldC8zZHMtbWV0aG9kLXJlZGlyZWN0aW9uLzVmOTUzZmI3LTA2YjQtNDlmYy1hNDI0LWVhMzRlODIzMjM4NS9WaXNhL3JlcXVlc3QvY2FsbGJhY2sifQ" id="threeDSMethodData" name="threeDSMethodData"/>
      <input type="submit" value="Go">
    </form>
  </body>
</html>

Example code - Challenge with no Method URL

{
  "transactionReference": "ca75295b-9d03-4294-9e97-312686884a43",
  "authenticationSessionId": "d886f14b-77c1-42b8-a632-da20d3551f4f",
  "redirectionFormData": {
    "actionUrl": "https://path.to/actionUrl",
    "threeDSSessionData": "MTIzNA",
    "creq": "eyJhY3NUcmFuc0lEIjoiNUUwRDhFQ0UtNDU0RC00QzkwLTk2QzMtMTRERTZFNTYxNjBFIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1IiwibWVzc2FnZVR5cGUiOiJDUmVxIiwibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiYTQxNzM4ZmUtM2NiNi00NmQzLTk1ZjctODcwNDVlNGRhN2YzIn0"
  },
  "authenticationPreparationResponse": {
    "authenticationStatus": "Required",
    "cavv": "AAABBEg0VhI0VniQEjRWAAAAAAA",
    "eci": "05",
    "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
  }
}

HTML page:

<html>
  <body>
    <form name="EventConfirmRedirection" method="post" action="https://path.to/actionUrl">
      <input type="hidden" value="eyJhY3NUcmFuc0lEIjoiNUUwRDhFQ0UtNDU0RC00QzkwLTk2QzMtMTRERTZFNTYxNjBFIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1IiwibWVzc2FnZVR5cGUiOiJDUmVxIiwibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiYTQxNzM4ZmUtM2NiNi00NmQzLTk1ZjctODcwNDVlNGRhN2YzIn0" id="creq" name="creq"/>
      <input type="hidden" value="MTIzNA" id="threeDSSessionData" name="threeDSSessionData"/>
      <input type="submit" value="Go">
    </form>
  </body>
</html>

3DSv2 Authorisation Flows

After receiving the Authentication response from Bambora, Merchant need to make decision to go ahead/ not go ahead with the Authorisation (Payment) process based on the Authentication result.

Merchant need to provide extra 3DSv2 details in the existing Payment API. The Payment response remains the same.

Sample 3DSv2 Purchase

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
  <soapenv:Header/>
  <soapenv:Body>
     
     <dts:SubmitSinglePayment>
    <!--Optional:-->
    <dts:trnXML>
    <![CDATA[
        <Transaction>
            <CustNumber>API-Purchase-Visa</CustNumber>                
            <CustRef>IPP-test</CustRef>
            <Amount>4000</Amount>
            <TrnType>1</TrnType>
            <CreditCard>		
                <CardNumber>4242424242424242</CardNumber>
                <ExpM>12</ExpM>
                <ExpY>2027</ExpY>
                <CVN>212</CVN>
                <ThreeDSv2>                  
                    <CAVV>AJkBBhgREQAAAAB4hABwcAAAAAA=</CAVV>
                    <ECI>05</ECI>
                    <TransactionReference>c4a4a0d8-832d-41d4-9560-f5dc7a2205ca</TransactionReference>
                    <XID>211c8d232-0fb9-4847-9dd8-9d6ce30ee83c</XID>
                </ThreeDSv2>
            </CreditCard>
            <PresentationType>EComm</PresentationType>
            <CredentialOnFile>
                <Type>Unscheduled</Type>
                <InitiatedBy>Customer</InitiatedBy>
            </CredentialOnFile>
            <Security>
                <UserName>auto.cofestd.api</UserName>
                <Password>Automation@123</Password>
            </Security>
        </Transaction>
    ]]>
    </dts:trnXML>
    </dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Specification for 3DSv2 fields in the Payment API

Custom Checkout

3DSv2 supports requests with an STT (Secure Transaction Token) in lieu of a PAN. With Custom Checkout you can generate a Secure Transaction Token to use.

The difference with 3D Secure Version 1 is that 3D Secure Version 2 is not called by our Payment API. Instead, there is an intermediate step which is to integrate 3DSv2 before calling our API with the outcome of the 3DSv2 flow.

API Request

The API Request is still a POST to https://threedsv2-api-nuat.bambora.net.au/v1/authentication with the same headers and largely the same request body as mentioned in the "Specification of Authentication messages" section of this document. The difference is that is no "card" root property in the request body there, so instead of the below:

"card": {
        "pan": "<test card>",
        "cardholderName": "C H Name",
        "expiryDate": {
            "month": 1,
            "year": 2022
        }
    }

you need to provide the Secure Transaction Token:

"stt":"<the Secure Transaction Token provided by Custom Checkout>"

Long Term Tokens

The API Request is still a POST to https://threedsv2-api-nuat.bambora.net.au/v1/authentication with the same headers and largely the same request body as mentioned in the "Specification of Authentication messages" section of this document. The difference is that is no "card" root property in the request body there, so instead of the below:

"card": {
        "pan": "<test card>",
        "cardholderName": "C H Name",
        "expiryDate": {
            "month": 1,
            "year": 2022
        }
    }

you need to provide the Long Term Token:

"bamboraToken": "<LTT>",

Integration summary

To call the 3DSv2 flow, before our Payment API is called to request a payment, you must call the 3DSv2 API to obtain authentication.

API Key

As mentioned, calls to 3DSv2 the API require an API Key. Please contact Bambora to receive one.

Callbacks

The outcome of the 3DSv2 flow will be communicated via a callback URL that must be provided to Bambora during onboarding. The notification will have a payload similar to the sample authentication notifications given above for any flow other than Frictionless with no Method URL. These notifications will contain the result of that flow which will determine whether to proceed with the transaction or not.