Guides
API Reference

3D Secure 2

In this section you will learn how to process a 3D Secure 2.0 authenticated transaction

Suggest Edits

❗️

PXP Exemption Engine - Coming soon

PXP will be further enhancing the 3D Secure Service to also include information to merchants about possible exemptions that could be utilised on a per transaction basis. This will be a future enhancement within the scaDetails object as shown below.

PXP will notify merchants once this becomes available.

Overview:

1447

Above is an overview of the 3D Secure 2.0 Flow & transaction processing (being invoked by the merchant)

1441

Above is an overview of the 3D Secure 2.0 Frictionless Flow & transaction processing (being automatically handled by PXP)

1438

Above is an overview of the 3D Secure 2.0 Challenge Flow & transaction processing (being automatically handled by PXP)

STEP 1: Pre-Authenticate the Card

🚧

clientSystemTransactionId

The clientSystemTransactionId should be unique per transaction, but maintained for the entire end to end 3D Secure process detailed in STEPS 1-6

📘

Optional Data Elements

Please note that 3D Secure 2.0 comes with many optional data elements which is designed to allow mechants to provide much more data to card issuers up front so they can perform analysis agasint the information received and compare to the information they already have for their cardholder. By doing this, the issuer is able to analyse risk better and maximise the chances of the payment being frictionless rather than challenge the card holder unnecessarily.

The more data elements provided, the higher the chance of Frictionless Authentication

An example of a 3D Secure Pre-Authentication request message can be seen below:

{
    "merchantId": "BDD",
    "storeId": "BDD500000001",
    "userId": "BDD-001",
    "type": "ecom.sale",
    "amount": "10.50",
    "currencyCode": "GBP",
    "clientSystemTransactionId": "UniqueTransactionRef01",
    "isAutoAuthorisationRequired": "true",
    "details": {
        "providerMerchantId": "12345678"
    },
    "accountDetails": {
        "cardNumber": "4012000000020006",
        "expiryDateMonth": 12,
        "expiryDateYear": 25
    },
    "storedCredentialDetails": {
        "cardOnfileIndicator": "cardHolderInitiatedCardOnFile"
    },
    "addressDetails": {
        "billingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        },
        "shippingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        }
    },
    "cardholderDetails": {
        "cardholderId": "82937a69-ff7e-4ec3-8985-56f221659e87",
        "cardholderName": "Joe Bloggs",
        "cardholderEmail": "[email protected]",
        "cardholderHomePhone": "44-207123456",
        "cardholderMobilePhone": "44-7712345678",
        "cardholderWorkPhone": "44-207123456"
    },
    "browserDetails": {
        "browserJavaEnabled": "true",
        "browserJavaScriptEnabled": "true",
        "browserLanguage": "en",
        "browserScreenHeight": "768",
        "browserScreenWidth": "1024",
        "browserTimeZone": "60",
        "browserScreenColorDepth": "24",
        "browserHeaderAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
        "browserHeaderUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.157 Safari/537.36",
        "browserChallengeWindowSize": "5",
        "browserIpAddress": "62.189.2.209"
    },
    "redirectDetails": {
        "fingerprintResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData",
        "challengeResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData"
    },
    "scaDetails": {
        "scaPolicy": "1",
        "scaChallengeIndicator": "requestNoChallenge",
        "scaExemption": null,
        "scaApplyExemptionAt": null
    }
}

{
    "merchantId": "BDD",
    "storeId": "BDD500000001",
    "userId": "BDD-001",
    "type": "ecom.sale",
    "amount": "10.50",
    "currencyCode": "GBP",
    "clientSystemTransactionId": "UniqueTransactionRef01",
    "isAutoAuthorisationRequired": "true",
    "details": {
        "providerMerchantId": "12345678"
    },
    "accountDetails": {
        "tokenId": "13c45dc2-56ec-4d7f-a966-50b6c3e93b37"
    },
    "storedCredentialDetails": {
        "cardOnfileIndicator": "cardHolderInitiatedCardOnFile"
    },
    "addressDetails": {
        "billingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        },
        "shippingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        }
    },
    "cardholderDetails": {
        "cardholderId": "82937a69-ff7e-4ec3-8985-56f221659e87",
        "cardholderName": "Joe Bloggs",
        "cardholderEmail": "[email protected]",
        "cardholderHomePhone": "44-207123456",
        "cardholderMobilePhone": "44-7712345678",
        "cardholderWorkPhone": "44-207123456"
    },
    "browserDetails": {
        "browserJavaEnabled": "true",
        "browserJavaScriptEnabled": "true",
        "browserLanguage": "en",
        "browserScreenHeight": "768",
        "browserScreenWidth": "1024",
        "browserTimeZone": "60",
        "browserScreenColorDepth": "24",
        "browserHeaderAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
        "browserHeaderUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.157 Safari/537.36",
        "browserChallengeWindowSize": "5",
        "browserIpAddress": "62.189.2.209"
    },
    "redirectDetails": {
        "fingerprintResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData",
        "challengeResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData"
    },
    "scaDetails": {
        "scaPolicy": "1",
        "scaChallengeIndicator": "requestNoChallenge",
        "scaExemption": null,
        "scaApplyExemptionAt": null
    }
}

{
    "merchantId": "BDD",
    "storeId": "BDD500000001",
    "userId": "BDD-001",
    "type": "ecom.sale",
    "amount": "10.50",
    "currencyCode": "GBP",
    "clientSystemTransactionId": "UniqueTransactionRef01",
    "isAutoAuthorisationRequired": "true",
    "details": {
        "providerMerchantId": "12345678"
    },
    "accountDetails": {
        "cardNumber": "Z8P+iPI8X4PTyOPQRbUOozDWqExFYaPkXgx6P51MLBc0SRAbYKA35UNiHw9TucgHV1XXTkIiwSDDu5mcJiJjAcUAq51+ybzPH/DB+DVNlkLn7ABaDudkHncRUhKruuWSnNl2OMTOs3C6XzYAB+zLi3hpBAHc7nCJxcQ35nungx0=",
        "expiryDateMonth": 12,
        "expiryDateYear": 25
    },
    "encryptionDetails": {
        "encryptionType": "rsaTwoFourZeroEight",
        "encryptionId": "13c45dc2-56ec-4d7f-a966-50b6c3e93b37"
    },
    "storedCredentialDetails": {
        "cardOnfileIndicator": "cardHolderInitiatedCardOnFile"
    },
    "addressDetails": {
        "billingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        },
        "shippingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        }
    },
    "cardholderDetails": {
        "cardholderId": "82937a69-ff7e-4ec3-8985-56f221659e87",
        "cardholderName": "Joe Bloggs",
        "cardholderEmail": "[email protected]",
        "cardholderHomePhone": "44-207123456",
        "cardholderMobilePhone": "44-7712345678",
        "cardholderWorkPhone": "44-207123456"
    },
    "browserDetails": {
        "browserJavaEnabled": "true",
        "browserJavaScriptEnabled": "true",
        "browserLanguage": "en",
        "browserScreenHeight": "768",
        "browserScreenWidth": "1024",
        "browserTimeZone": "60",
        "browserScreenColorDepth": "24",
        "browserHeaderAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
        "browserHeaderUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.157 Safari/537.36",
        "browserChallengeWindowSize": "5",
        "browserIpAddress": "62.189.2.209"
    },
    "redirectDetails": {
        "fingerprintResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData",
        "challengeResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData"
    },
    "scaDetails": {
        "scaPolicy": "1",
        "scaChallengeIndicator": "requestNoChallenge",
        "scaExemption": null,
        "scaApplyExemptionAt": null
    }
}

{
    "merchantId": "BDD",
    "storeId": "BDD500000001",
    "userId": "BDD-001",
    "type": "ecom.sale",
    "amount": "10.50",
    "currencyCode": "GBP",
    "clientSystemTransactionId": "UniqueTransactionRef01",
    "isAutoAuthorisationRequired": "true",
    "details": {
        "providerMerchantId": "12345678"
    },
    "accountDetails": {
        "cardTokenizedNumber": "9946000000000090483",
        "expiryDateMonth": 12,
        "expiryDateYear": 25
    },
    "storedCredentialDetails": {
        "cardOnfileIndicator": "cardHolderInitiatedCardOnFile"
    },
    "addressDetails": {
        "billingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        },
        "shippingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "countryCode": "GBR"
        }
    },
    "cardholderDetails": {
        "cardholderId": "82937a69-ff7e-4ec3-8985-56f221659e87",
        "cardholderName": "Joe Bloggs",
        "cardholderEmail": "[email protected]",
        "cardholderHomePhone": "44-207123456",
        "cardholderMobilePhone": "44-7712345678",
        "cardholderWorkPhone": "44-207123456"
    },
    "browserDetails": {
        "browserJavaEnabled": "true",
        "browserJavaScriptEnabled": "true",
        "browserLanguage": "en",
        "browserScreenHeight": "768",
        "browserScreenWidth": "1024",
        "browserTimeZone": "60",
        "browserScreenColorDepth": "24",
        "browserHeaderAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
        "browserHeaderUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.157 Safari/537.36",
        "browserChallengeWindowSize": "5",
        "browserIpAddress": "62.189.2.209"
    },
    "redirectDetails": {
        "fingerprintResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData",
        "challengeResultUrl": "https://api-integration.pxp-solutions.net/MerchantSystemService/MpiListener/MerchantData"
    },
    "scaDetails": {
        "scaPolicy": "1",
        "scaChallengeIndicator": "requestNoChallenge",
        "scaExemption": null,
        "scaApplyExemptionAt": null
    }
}

📘

isAutoAuthorisationRequired element

If isAutoAuthorisationRequired is included and set to true, PXP will automatically analyse the 3D Secure response at STEP 3 and perform the authorisation to the acquirer (STEP 4) on the merchant's behalf. In this scenario, the response you receive in STEP 3 will be an authorisation response and STEP 4 will not be applicable

Note: If the card is not 3DS 2.0 capable and is NotEnrolled, then a "NotEnrolled" response will be received and automatic authorisation will not be invoked. If the merchant wishes to continue, then they may do so by sending in a transaction request directly to the Transaction Service at their discretion

An example of a 3D Secure Pre-Authentication response message can be seen below:

{
    "state": "PreAuthenticated",
    "cardType": "card.visa",
    "accountDetails": {
        "tokenizedCardNumber": "9997000000005070006",
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "mpiSessionId": "cd0a5e47-1270-4599-9b35-ea07755ab2aa",
        "accessControlServerUrl": "https://api.test.kalixa.com/WebMockProviders/threedsv2acs/fingerprint",
        "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tZXJjaGFudHdlYi5weHAtc29sdXRpb25zLm5ldC92NC9LYWxpeGEvS2FsaXhhUmV0dXJuLmFzcD8iLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImI0MWU4YWI2LTI1MTYtNDc4My05ZGI4LTMxNjExMzY0OTkyMSJ9"
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

{
    "state": "Enrolled",
    "cardType": "card.visa",
    "accountDetails": {
        "tokenizedCardNumber": "9997000000005071111",
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "1.0.2",
        "mpiSessionId": "393a0c43-ec94-415d-bce9-5a0517707791",
        "accessControlServerUrl": "https://checkout-integration.pxp-solutions.net/WebMockProviders/CreditCards/3DSecure/ThreeDSecureAuthentificate.aspx?processingMode=Automatic&useStoredCertificate=false",
        "paReq": "eNpVUt9vgjAQ/lcI79IWFYs5atgwmQ8as7lkrwQ6ZZGCUAbbX78rwtSHS++7Xu/H9xVWXX62vmVVZ4UKbOZQ25IqKdJMHQO70Z8Tblu1jlUanwslA1sV9krA4VRJGb3JpKmkgK2s6/gorSwN7HDizikamzDu0QVltoB9+CovAoYuAps4LpAR4vMqOcVKC4iTy9NmJ2aev5hyIAOEXFabSHic+T7F8BWCinMp9h97BqR3ISkapasfwV0PyAigqc7ipHW5JKRtW6fsykldnBuNrWsnKXIgJgPIbYp9Y7waK3ZZKrZR2D7aerb7Cqd4BkBMBqSxlsKljFPucovNly5fTn0gfRzi3IwiGHUoxZ2uCErTJByvzM19BJDYCnUYlxkRyK5EGTADCfz3IZV1gisMx23+5xfDaaKRrl207raHe3vvdr/9SoFhuk8y5TMkzUXd+voGADFlyCAiGcRG7+ET/AELab/r",
        "merchantData": "oQ/45UJwJnDBxMYzu4m3eMA+0q4qGfrZrMtXdqVHDP2yVYg6nZD/+ExRpVETNQT8HmuO9PKs7B4="
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

{
    "state": "NotEnrolled",
    "cardType": "card.visa",
    "accountDetails": {
        "tokenizedCardNumber": "9997000000005071111",
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "1.0.2",
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

{
    "code": "4000340",
    "details": {
        "message": "Unable to verify enrollment status of card"
    }
}

{
    "state": "FrictionlessAuthenticated",
    "cardType": "card.visa",
    "accountDetails": {
        "tokenizedCardNumber": "9909000000000036631"
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": "05",
        "cavv": "MTYzNTE3MDQ2ODE4MjA3Mzk2NDI=",
        "dsTransId": "0c347a4b-6de0-4d66-8c09-e5e1b88e498e",
        "transactionStatus": "Y"
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

{
    "state": "FrictionlessNotAuthenticated",
    "cardType": "card.visa",
    "accountDetails": {
        "tokenizedCardNumber": "9979000000000044385"
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "82a686a2-0f50-4a0e-83a1-5d0ced897d73",
        "transactionStatus": "N",
        "transactionStatusReason": "Security failure"
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

{
    "state": "FrictionlessRejected",
    "cardType": "card.visa",
    "accountDetails": {
        "tokenizedCardNumber": "9979000000000044385"
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "82a686a2-0f50-4a0e-83a1-5d0ced897d73",
        "transactionStatus": "R",
        "transactionStatusReason": "Security failure"
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

{
    "id": "484cecc3-b296-40f5-a7c8-a3d9d8e8a7f2",
    "state": "Authorised",
    "providerStateCode": "A",
    "currencyCode": "GBP",
    "accountDetails": {
        "cardNumber": "411111******1111",
        "tokenizedCardNumber": "9902000000000441111",
        "isVisaCheckout": null
    },
    "details": {
        "providerMerchantId": "542929008043127",
        "providerTerminalId": "00630376"
    },
    "stateDetails": {
        "approvalCode": "415810"
    },
    "cardSecurityResponseCode": null,
    "addressVerificationResponseCode": null
}

{
    "state": "ChallengeRequired",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "mpiSessionId": "393a0c43-ec94-415d-bce9-5a0517707791",
        "challengeRedirectUrl": "http://dummy-acs-challange-url.com/script",
        "cReq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMTgwMDA4Ny00MmU4LTQ0MWMtYmMwYS1hYjI2OTBmOTU4YzQiLCJhY3NUcmFuc0lEIjoiZGE4NzdjZmUtODkwYi00ZWYwLTkyZDktZDM2OGMzNzQ1ZThiIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0=",
        "transactionStatus": "C"
    },
    "scaDetails": {
        "scaExemptionEngineResult": "noExemptionAvailable"
    }
}

🚧

PSD2 Exemptions:

Please note that the scaDetails object is not yet available for either the request or response.
PXP will notify merchants once this becomes available.

📘

Pre-Authentication Response State

Fingerprinting is supported by the card issuer
If the state received in the response is PreAuthenticated, then continue to STEP 2

Fingerprinting not supported by the card issuer
If a card issuer does not support device fingerprinting, then PXP will bypass this process and invoke the call to scheme's 3D Secure Server immediately and return the response in the PreAuthentication Response.

If the state received in the response is FrictionlessAuthenticated, Attempted or Unavailable then continue to STEP 6 with the required data in the threeDsecure object.
If the state received in the response is ChallengeRequired, then continue to STEP 4.1

Note:
If isAutoAuthorisationRequired is set to true in STEP 1, then PXP will analyse the 3D Secure state on the merchant's behalf and automatically proceed for authorisation with the 3D Secure data if Frictionless Authentication was achieved / attempted and return a Card Transaction Response. In this scenario, the transaction is now complete. and STEP 6 is not required.

This applies to the below states:
FrictionlessAuthenticated
Attempted
Unavailable

❗️

Pre-Authentication Response State

If the state received in the response is FrictionlessNotAuthenticated or FrictionlessRejected, then the transaction should be aborted and NOT proceed for authorisation**

🚧

Please Note:

The {mpiSessionId} is required later on in STEP 3 and STEP 5 respectively so should be stored for the duration of the process.

STEP 2.1: Perform Device Fingerprinting via the ACS

Once the Pre-Authentication response has been received, you will be required to create a hidden iFrame and POST the threeDSMethodData to the accessControlServerUrl to allow the Issuer/ACS to collect data from the browser / device to build a risk profile for the transaction

The fingerprint response will be be POSTed from the ACS to the fingerprintResultUrl which was provided in STEP 1.

Below is an iFrame sample showing which data should be posted and to where

<form name="Fingerprinting" method="POST" action="https://api.test.kalixa.com/WebMockProviders/threedsv2acs/fingerprint">
	<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tZXJjaGFudHdlYi5weHAtc29sdXRpb25zLm5ldC92NC9LYWxpeGEvS2FsaXhhUmV0dXJuLmFzcD8iLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImI0MWU4YWI2LTI1MTYtNDc4My05ZGI4LTMxNjExMzY0OTkyMSJ9" />
</form>

Below is an interactive form that showcases the iFrame Post. (Which is not hidden for demonstration purposes)

POST the threeDSMethodData form data to the accessControlServerUrl obtained from the
3DS Pre-Authentication Response

accessControlServerUrl

STEP 2.2 Receive the Fingerprint Response (threeDSMethodData) from the Access Control Server (ACS)

The ACS will POST the fingerprint response back to the fingerprintResultUrl as specified in STEP 1.

The merchant will receive the threeDSMethodData from the ACS in a URL Encoded format and will need to URL Decode it before submitting in STEP 3:

PXP's 3DS Listener has automatically URL Decoded the data as shown above.

If no response is received by the ACS within 10 seconds, then proceed to STEP 3 without the Fingerprint response data which will represented as null as per the example

STEP 3: Authentication - Frictionless Flow

An example of a 3D Secure Authentication request message can be seen below:

{
    "merchantId": "BDD",
    "storeId": "BDD500000005",
    "userId": "BDDTest",
    "clientSystemInvoiceId": "TestTransactionReference",
    "clientSystemTransactionId": "TestTransactionReference",
    "threeDSecureDetails": {
        "mpiSessionId": "393a0c43-ec94-415d-bce9-5a0517707791",
        "threeDSMethodData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImI0MWU4YWI2LTI1MTYtNDc4My05ZGI4LTMxNjExMzY0OTkyMSJ9"
    }
}

{
    "merchantId": "BDD",
    "storeId": "BDD500000005",
    "userId": "BDDTest",
    "clientSystemInvoiceId": "TestTransactionReference",
    "clientSystemTransactionId": "TestTransactionReference",
    "threeDSecureDetails": {
        "mpiSessionId": "393a0c43-ec94-415d-bce9-5a0517707791",
        "threeDSMethodData": null
    }
}

📘

isAutoAuthorisationRequired

If this was set to true in STEP 1, then PXP will analyse the 3D Secure state on the merchant's behalf and automatically proceed for authorisation with the 3D Secure data if Frictionless Authentication was achieved / attempted and return a Card Transaction Response. In this scenario, the transaction is now complete. and STEP 6 is not required.

This applies to the below states:
FrictionlessAuthenticated
Attempted
Unavailable

An example of a 3D Secure Authentication response message can be seen below:

{
    "state": "FrictionlessAuthenticated",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": "05",
        "cavv": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "Y"
    }
}

{
    "state": "ChallengeRequired",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "challengeRedirectUrl": "https://v3dstestsuite.3dsecure.net/V3DSTestSuiteService2/acs2Service/browserCReq",
        "cReq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMTgwMDA4Ny00MmU4LTQ0MWMtYmMwYS1hYjI2OTBmOTU4YzQiLCJhY3NUcmFuc0lEIjoiZGE4NzdjZmUtODkwYi00ZWYwLTkyZDktZDM2OGMzNzQ1ZThiIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0=",
        "transactionStatus": "C"
    }
}

{
    "state": "FrictionlessNotAuthenticated",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "N",
        "transactionStatusReason": "Security failure"
    }
}

{
    "state": "FrictionlessRejected",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "R",
        "transactionStatusReason": "Security failure"
    }
}

{
    "id": "484cecc3-b296-40f5-a7c8-a3d9d8e8a7f2",
    "state": "Authorised",
    "providerStateCode": "A",
    "currencyCode": "GBP",
    "accountDetails": {
        "cardNumber": "411111******1111",
        "tokenizedCardNumber": "9902000000000441111",
        "isVisaCheckout": null
    },
    "details": {
        "providerMerchantId": "542929008043127",
        "providerTerminalId": "00630376"
    },
    "stateDetails": {
        "approvalCode": "415810"
    },
    "cardSecurityResponseCode": null,
    "addressVerificationResponseCode": null
}

{
    "state": "Attempted",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": "06",
        "cavv": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "A"
    }
}

{
    "state": "Unavailable",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "U",
        "transactionStatusReason": "Security failure",
    }
}

📘

Authentication Response State

If the state received in the response is FrictionlessAuthenticated, Attempted or Unavailable then continue to STEP 6 with the required data in the threeDsecure object
If the state received in the response is ChallengeRequired, then continue to STEP 4.1

❗️

If the state received in the response is FrictionlessNotAuthenticated or FrictionlessRejected, then the transaction should be aborted and NOT proceed for authorisation**

STEP 4.1: Invoke Cardholder Challenge via an iFrame (Challenge Flow)

Once the Authentication response has been received, if the state is ChallengeRequired, you will be required to create an iFrame and POST the creq to the challengeRedirectUrl which will display the card issuer's ACS challenge screen and allow the card holder to enter their details (One time Password / Biometrics etc...)

The challenge response (cres) will be be POSTed from the ACS to the challengeResultUrl which was provided in STEP 1.

Below is an iFrame sample showing which data should be posted and to where 

<form name="iFrameChallengePost" method="POST" action="https://v3dstestsuite.3dsecure.net/V3DSTestSuiteService2/acs2Service/browserCReq">
	<input name="creq" value="eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJiNDFlOGFiNi0yNTE2LTQ3ODMtOWRiOC0zMTYxMTM2NDk5MjEiLCJhY3NUcmFuc0lEIjoiZjlmZWJhZTEtYTAyOC00ZDg2LTkxYzAtMmJjZTAwMDMzMWMxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0" />
</form>

📘

Challenge POST

  • The field "creq" MUST be lowercase when POSTing to the challengeRedirectUrl
challengeRedirectUrl

STEP 4.2: Recieve the Challenge Response (cres) from the Access Control Server (ACS)

The ACS will POST the Challenge Response (cres) back to the challengeResultUrl which was provided in STEP 1.

The merchant will receive the data from the ACS in a URL Encoded format and will need to URL Decode it before submitting in STEP 5:

PXP's 3DS Listener has automatically URL Decoded the data as shown above.

STEP 5: Collect Authentication Results following a Challenge

An example of a 3D Secure Challenge request message can be seen below:

{
    "merchantId": "BDD",
    "storeId": "BDD500000005",
    "userId": "BDDTest",
    "clientSystemInvoiceId": "1-2",
    "clientSystemTransactionId": "1-2",
    "threeDSecureDetails": {
        "mpiSessionId": "393a0c43-ec94-415d-bce9-5a0517707791",
        "cRes": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImI0MWU4YWI2LTI1MTYtNDc4My05ZGI4LTMxNjExMzY0OTkyMSIsImFjc1RyYW5zSUQiOiJmOWZlYmFlMS1hMDI4LTRkODYtOTFjMC0yYmNlMDAwMzMxYzEiLCJlcnJvckNvZGUiOiIzMDUiLCJlcnJvckNvbXBvbmVudCI6IkQiLCJlcnJvckRlc2NyaXB0aW9uIjoiVHJhbnNhY3Rpb24gZGF0YSBub3QgdmFsaWQiLCJlcnJvckRldGFpbCI6InRocmVlRFNTZXJ2ZXJUcmFuc0lEIiwiZXJyb3JNZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVHlwZSI6IkVycm8iLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0"
    }
}

📘

isAutoAuthorisationRequired

If this was set to true in STEP 1, then PXP will analyse the 3D Secure state on the merchant's behalf and automatically proceed for authorisation with the 3D Secure data if ChallengeAuthenticated was achieved / attempted and return a Card Transaction Response. In this scenario, the transaction is now complete. and STEP 6 is not required.

This applies to the below states:
ChallengeAuthenticated
Attempted
Unavailable

If the challenge was not successful for any reason, then the Challenge Response will be returned with ChallengeNotAuthenticated or ChallengeRejected to notify you of this.

An example of a 3D Secure Challenge response message can be seen below:

{
    "state": "ChallengeAuthenticated",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": "05",
        "cavv": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "Y"
    }
}

{
    "state": "ChallengeNotAuthenticated",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "N",
        "transactionStatusReason": "Card authentication failed",
    }
}

{
    "state": "ChallengeRejected",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "R",
        "transactionStatusReason": "Card authentication failed",
    }
}

{
    "id": "484cecc3-b296-40f5-a7c8-a3d9d8e8a7f2",
    "state": "Authorised",
    "providerStateCode": "A",
    "currencyCode": "GBP",
    "accountDetails": {
        "cardNumber": "411111******1111",
        "tokenizedCardNumber": "9902000000000441111",
        "isVisaCheckout": null
    },
    "details": {
        "providerMerchantId": "542929008043127",
        "providerTerminalId": "00630376"
    },
    "stateDetails": {
        "approvalCode": "415810"
    },
    "cardSecurityResponseCode": null,
    "addressVerificationResponseCode": null
}

{
    "state": "Unavailable",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": null,
        "cavv": null,
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "U"
    }
}

{
    "state": "Attempted",
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "eci": "06",
        "cavv": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "transactionStatus": "A"
    }
}

❗️

If the state received is "ChallengeNotAuthenticated" or "ChallengeRejected" then the payment should be aborted and should NOT proceed to STEP 6

STEP 6: Process a Payment with the 3D Secure Authentication Data

An example of a Card Transaction request message with 3DS Data can be seen below:

The merchant will need to include the threeDSecureDetails object and corresponding elements.

{
    "merchantId": "PXP",
    "storeId": "PXP000000001",
    "userId": "PxpUser1",
    "type": "ecom.sale",
    "amount": "10.00",
    "currencyCode": "GBP",
    "clientSystemInvoiceId": "UniqueReference1",
    "clientSystemTransactionId": "UniqueReference1",
    "accountDetails": {
        "cardNumber": "4111111111111111",
        "expiryDateMonth": 12,
        "expiryDateYear": 25
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "status": "FrictionlessAuthenticated",
        "eci": "05",
        "cavv": "MTMwMjQ2MDQxMTAxMTU2OTc5MTc=",
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
    },
    "cardVerificationDetails": {
        "cardVerificationValue": "123"
    },
    "addressVerificationDetails": {
        "address": "1",
        "zipPostalCode": "SG12 8XL",
        "countryCode": "GB"
    }
}

{
    "merchantId": "PXP",
    "storeId": "PXP000000001",
    "userId": "PxpUser1",
    "type": "ecom.sale",
    "amount": "10.00",
    "currencyCode": "GBP",
    "clientSystemInvoiceId": "UniqueReference1",
    "clientSystemTransactionId": "UniqueReference1",
    "accountDetails": {
        "cardNumber": "4111111111111111",
        "expiryDateMonth": 12,
        "expiryDateYear": 25
    },
    "threeDSecureDetails": {
        "threeDSecureVersion": "2.1.0",
        "status": "ChallengeAuthenticated",
        "eci": "05",
        "cavv": "MTMwMjQ2MDQxMTAxMTU2OTc5MTc=",
        "dsTransId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b"
    },
    "cardVerificationDetails": {
        "cardVerificationValue": "123"
    },
    "addressVerificationDetails": {
        "address": "1",
        "zipPostalCode": "SG12 8XL",
        "countryCode": "GB"
    }
}

An example of a Card Transaction response message can be seen below:

{
    "id": "484cecc3-b296-40f5-a7c8-a3d9d8e8a7f2",
    "state": "Authorised",
    "providerStateCode": "A",
    "currencyCode": "GBP",
    "accountDetails": {
        "cardNumber": "411111******1111",
        "tokenizedCardNumber": "9902000000000441111",
        "isVisaCheckout": null
    },
    "details": {
        "providerMerchantId": "542929008043127",
        "providerTerminalId": "00630376"
    },
    "stateDetails": {
        "approvalCode": "415810"
    },
    "cardSecurityResponseCode": null,
    "addressVerificationResponseCode": null
}

Updated 5 months ago