3D Secure 2
In this section you will learn how to process a 3D Secure 2.0 authenticated transaction
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:
Above is an overview of the 3D Secure 2.0 Flow & transaction processing (being invoked by the merchant)
Above is an overview of the 3D Secure 2.0 Frictionless Flow & transaction processing (being automatically handled by PXP)
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 for 3D Secure 1.0, 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 2Fingerprinting 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.13DS 2.0 Not Supported - Fallback to 3DS 1.0
If the state received in the response is Enrolled, then fall back to 3D Secure 1.0 STEP 2
If the state received in the response is NotEnrolled, then continue to STEP 6 with with a state of "NotEnrolled" in the threeDsecure objectNote:
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
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
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
UnavailableIf 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 over 3 years ago