Browser-based flow for 3DS 2.0 - Authentication-Only payments
Introduction
This page aims to describe the 3DS 2.0 authentication-only flow to merchants with a backend-to-backend integration to the PXP Financial Payment Service.
An authentication-only payment can be used when a merchant only requires to perform 3DS2 authentication and authorisation is not required until later.
After the 3DS 2.0 authentication data has been returned successfully for an authentication-only payment, a 3DS 2.0 Pass through payment can be initiated through PXP Financial using the relevant data fields, or the payment can be authorised through another Payment Service Provider.
In this flow, a merchant will perform 3DS 2.0 authentication without authorisation.
Process Overview
An authentication only flow is initiated from a Merchant front-end, via a backend-to-backend call to PXP Financial. 3DS 2.0 Authentication is initiated, with the user experience being determined by either a frictionless or a challenge flow.
Pre-requisites
- You must have a test account set up for use with PXP Financial
- If you are an existing merchant you should already have a fully integrated backend-to-backend integration in place
- If you are a new merchant please refer to the Initiate New Payment (Backend2Backend) section
Integration Steps
Step 1: Create a new payment
Submit initiatePaymentRequest
initiatePaymentRequest
The initiatePaymentRequest
has been extended with new fields relevant to 3DS 2.0 authentication. Existing merchants will need to extend their existing integration and send these fields in addition to those that they usually send.
Refer to the table from our main browser-based flow page which lists the 3DS 2.0 fields that should be sent in the initiatePaymentRequest
(API documentation about initiatePaymentRequest
can be located here).
Payment Method ID
The
PaymentMethodID
must be set to 345 for an authentication-only payment.
The merchant must send in addition the Acquirer BIN and the Acquirer MID (Merchant ID) in the initiatePaymentRequest
. This information will be used for the 3DS check.
Field | Description | Required |
---|---|---|
AcquirerMID | The merchant ID as assigned by the Acquirer | Y |
AcquirerBIN | Acquiring institution identification code as assigned by the Scheme | Y |
ThreeDSecureRequestorID | Unique identifier assigned by Scheme following 3DS2 enrolment. This must be provided if you are authorising through a different Acquirer or Gateway. | Y |
Consistence of Acquirer BIN and Acquirer MID in authentication and authorisation
Merchants are advised to ensure the Acquirer BIN and Acquirer MID are the same both in authentication and authorization requests. In case there is a difference, the payment will be rejected by Issuer.
Note: Validation of required parameters will not be performed but if the payment goes through the 3DS 2.0 process and required parameters are missing it will fail.
Payments with '0' amount
There are two ways for submitting
initiatePaymentRequest
for a payment with '0' amount:
- Do not send the
amount
element at all- Send '0' amount together with
currencyCode
attribute
Additional Information means a greater chance for a Frictionless flow
The more data points are submitted the better chances the cardholder has for a frictionless authentication
Example initiatePaymentRequest
:
<?xml version="1.0" encoding="UTF-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<merchantID>3DSv2_TestMerchant</merchantID>
<shopID>3DSv2_TestShop</shopID>
<merchantTransactionID>852e88bd-3049-4c59-8fc5-f02ba65ccd3b</merchantTransactionID>
<paymentMethodID>345</paymentMethodID>
<userID>dd42ee1b-daab-40d4-8d04-82bf7ea7a53e</userID>
<userData>
<username>V3DSv2TesUser</username>
<firstname>John</firstname>
<lastname>Doe</lastname>
<currencyCode>EUR</currencyCode>
<languageCode>EN</languageCode>
<email>[email protected]</email>
<address>
<street>Marxergasse</street>
<houseNumber>1b</houseNumber>
<postalCode>1030</postalCode>
<city>Vienna</city>
<countryCode2>AT</countryCode2>
<telephoneNumber>044-52186</telephoneNumber>
</address>
<gender>Male</gender>
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>96f4bca1-5e2b-4fc2-9d2d-540feaef1609</userSessionID>
<creationTypeID>3</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>626e7c42-bf0e-45fe-9e6c-54e8353ad0b8</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescriptionLanguageCode</key>
<value>en</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>IsThreeDSecureRequired</key>
<value>true</value>
</data>
<!--<data xsi:type="keyIntValuePair">
<key>PaymentProviderID</key>
<value>92</value>
</data>-->
<data xsi:type="keyStringValuePair">
<key>BrowserVerificationNotificationURL</key>
<value>https://www.notification.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserLanguage</key>
<value>en</value>
</data>
<data xsi:type="keyIntValuePair">
<key>BrowserScreenHeight</key>
<value>768</value>
</data>
<data xsi:type="keyIntValuePair">
<key>BrowserScreenWidth</key>
<value>1024</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserTimeZone</key>
<value>UTC</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>BrowserJavaEnabled</key>
<value>true</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>BrowserJavaScriptEnabled</key>
<value>true</value>
</data>
<data xsi:type="keyIntValuePair">
<key>BrowserScreenColorDepth</key>
<value>15</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderAccept</key>
<value>BrowserHeaderAccept</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderUserAgent</key>
<value>BrowserHeaderUserAgent</value>
</data>
<data xsi:type="keyIntValuePair">
<key>UserVerificationWindowSize</key>
<value>60</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserVerificationNotificationURL</key>
<value>https://api.test2.kalixa.com/WebMockProviders/threedsv2acs/showcres</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardholderHomePhone</key>
<value>044-52186</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardholderMobilePhone</key>
<value>051-813678</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardholderWorkPhone</key>
<value>044-13281</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardholderEmail</key>
<value>[email protected]</value>
</data>
<data xsi:type="keyStringValuePair">
<key>AcquirerMID</key>
<value>7171021111000</value>
</data>
<data xsi:type="keyStringValuePair">
<key>AcquirerBIN</key>
<value>491677</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ThreeDSecureRequestorID</key>
<value>100679177171021111</value>
</data>
</specificPaymentData>
<paymentAccount>
<specificPaymentAccountData>
<data xsi:type="keyStringValuePair">
<key>CardNumber</key>
<value>5301250070000191</value>
</data>
<data xsi:type="keyStringValuePair">
<key>HolderName</key>
<value>John Doe</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryMonth</key>
<value>12</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryYear</key>
<value>2030</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardVerificationCode</key>
<value>111</value>
</data>
</specificPaymentAccountData>
</paymentAccount>
</initiatePaymentRequest>
Receive initiatePaymentResponse
initiatePaymentResponse
Information about the 3DS related fields returned in initiatePaymentResponse
can be found here.
Further details on initiatePaymentResponse
can be found here
.
Below table contains the specific fields for authentication-only payments returned in initiatePaymentResponse
/ executePaymentActionResponse
:
Field | Description |
---|---|
IsFictionlessAuthenticated | Indicates whether the payment has been successfully authenticated during frictionless flow. Possible values: true/ false |
IsScaMandated | Indicates if Strong Customer Authentications is mandatory as evaluated by PXP's Payment Service. Possible values: true/ false |
Example initiatePaymentResponse
:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>3DSv2_TestMerchant</merchantID>
<shopID>3DSv2_TestShop</shopID>
<paymentMethod>
<key>345</key>
<value>ThreeDSecureCardAuthentication</value>
</paymentMethod>
<merchantTransactionID>852e88bd-3049-4c59-8fc5-f02ba65ccd3b</merchantTransactionID>
<paymentID>35076dd0-e138-4cbf-83a4-41a39658665f</paymentID>
<userID>dd42ee1b-daab-40d4-8d04-82bf7ea7a53e</userID>
<paymentProvider>
<key>92</key>
<value>CQRUK</value>
</paymentProvider>
<amount currencyCode="EUR">10</amount>
<creationType>
<key>3</key>
<value>Api</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>8dfa209e-c501-4eb4-9a29-0a44e53a4b03</id>
<definition>
<key>581</key>
<value>PendingOnClientDeviceDataCollection</value>
</definition>
<createdOn>2019-07-02T16:10:34.7624501Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectUrl</key>
<value>https://api.test2.kalixa.com/WebMockProviders/threedsv2acs/fingerprint</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>RedirectPostData</key>
<value>threeDSMethodData=eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93d3cubm90aWZpY2F0aW9uLmNvbSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMzUwNzZkZDAtZTEzOC00Y2JmLTgzYTQtNDFhMzk2NTg2NjVmIn0=</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">10</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ElectronicCommerceIndicator</key>
<value>07</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ThreeDSecureVersion</key>
<value>2</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>18da3dbb-f493-4318-946a-5a998d339974</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Step 2: Perform device fingerprinting
Integration steps for performing device fingerprinting are described here.
Step 3: PXP Financial performs authentication
Frictionless Authentication
If the state of the payment returned in initiatePaymentResponse
or HandleClientDeviceDataCollection
action response is 291 (AuthenticatedByThreeDSecure) then challenge is not required. IsFictionlessAuthenticated
field with value 'true' is returned to indicate that the payment has been successfully authenticated during frictionless flow.The authentication process stops here.
Example code sample with IsFictionlessAuthenticated
field:
...
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ElectronicCommerceIndicator</key>
<value>05</value>
</detail>
<detail xsi:type="keyBooleanValuePair">
<key>IsScaMandated</key>
<value>true</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ThreeDSecureVersion</key>
<value>2.1.0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>CardholderAuthenticationVerificationValue</key>
<value>MTIwODc5OTgyMTAzOTAwMzE2ODk=</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ThreeDSecureTransactionStatus</key>
<value>Y</value>
</detail>
<detail xsi:type="keyBooleanValuePair">
<key>IsFrictionlessAuthenticated</key>
<value>true</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>DirectoryServerTransactionID</key>
<value>7b5fed48-70d2-4812-a8ca-56ec115ba35f</value>
</detail>
</paymentDetails>
...
Challenge requested
Explanation about the fields related to performing challenge can be found here. If challenge is required the value of IsFrictionlessAuthenticated
is false.
Step 4: Perform Challenge Flow
Follow the instructions described here to perform challenge.
If challenge is successful, 291 (AuthenticatedByThreeDSecure) is returned in HandleUserVerification
action response.
Step 5: Complete Authorisation
After the 3DS 2.0 authentication data has been returned, a 3DS 2.0 Pass through payment can be initiated through PXP Financial or the payment can be authorised through another Payment Service Provider.
3DS 1.0 Fallback
When the payment request is received by PXP Financial, we check if 3DS 2.0 is supported for the card. If not, the payment is processed through 3DS 1.0 pass-through flow.
Please note that successful fallback to 3DS 1.0 requires sending additional fields in the InitiatePaymentRequest.The additional fields are described here.
For more information about 3DS 1.0 please refer to Card Deposits with 3DS section.
Failed authentication
If authentication hasn't been successful (authentication failed either in frictionless or challenge flow), merchant will receive a reason code in ThreeDSecureTransactionStatusReason
.
One of the following states is returned for a payment with failed authentication:
- UserAuthenticationFailed (587) - when authentication fails during frictionless flow
- UserAuthenticationErrorOccurred (600) - when an error occurs during frictionless flow
- UserVerificationFailed (592) - when authentication fails during challenge flow
- UserVerificationErrorOccurred (599) - this state is returned in shop notifications during challenge flow.
One of the following states is returned for a payment with declined authentication:
- 597 (UserAuthenticationRejected) - when payment is declined during frictionless flow
- 598 (UserVerificationRejected) - when payment is declined during challenge flow.
Payments in these states have ECI value = 07.
Possible values for TransactionStatusReason
:
ID | Description |
---|---|
01 | Card authentication failed |
02 | Unknown Device |
03 | Unsupported Device |
04 | Exceeds authentication frequency limit |
05 | Expired card |
06 | Invalid card number |
07 | Invalid transaction |
08 | No Card record |
09 | Security failure |
10 | Stolen card |
11 | Suspected fraud |
12 | Transaction not permitted to cardholder |
13 | Cardholder not enrolled in service |
14 | Transaction timed out at the ACS |
15 | Low confidence |
16 | Medium confidence |
17 | High confidence |
18 | Very High confidence |
19 | Exceeds ACS maximum challenges |
20 | Non-Payment transaction not supported |
21 | 3RI transaction not supported |
22 | ACS technical issue |
23 | Decoupled Authentication required by ACS but not requested by 3DS Requestor |
24 | 3DS Requestor Decoupled Max Expiry Time exceeded |
25 | Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt |
26 | Authentication attempted but not performed by the cardholder |
3DS 2.0 authentication only Integration Summary
In order to integrate with PXP Finanacial for a 3DS 2.0 authentication only payment you will need to:
- Send additional data in
initiatePaymentRequest
- Perform Device Fingerprinting using a listener you have implemented
- Notify PXP Financial of the result
- In a frictionless flow, proceed with the authorisation with PXP Financial or another Payment Service Provider
- In case of a challenge flow, perform the challenge using a second listener you have implemented
- Forward the results to PXP Financial
- PXP Financial will notify you of the authentication result
3DS Test Scripts
3DS Test scripts can be found here.
Version History
Date | Description |
---|---|
22.12.2022 | Initial publication |
Updated 9 months ago