Card Deposits with 3DS
IMPORTANT: 3DS1 is deprecated globally. Refer to 3DS2 documentation
Our 3DS 2.0 documentation is ready to review! Our 3DS 2.0 Information Hub can be found here
Please do not use any 3DS1 functionality going forward.
Card deposits can be further secured by implementing the 3D Secure (3DS) protocol (3D Secure = Three Domain Secure, see wikipedia for further information).
The basic concept of the protocol is to link the card payment authorization process with cardholder authentication – the cardholder is redirected to a web site (e.g. of the card issuing bank) where she/he must authenticate her/himself.
Mastercard SecureCode and Verified by Visa
The implementations of Mastercard and Visa of the 3DS protocol are called Mastercard SecureCode and Verified by Visa.
3D Secure is an authentication mechanism that can protect a merchant against the most common fraud-related chargeback reasons. The liability shifts to the Card Issuer ("Liability Shift"). There are also cases that do not require the customer to fully authenticate, yet would still result in a liability shift.
For Visa and Mastercard (incl. Maestro), the chargeback reasons that 3DS protects against are:
| Card Scheme | Chargeback Reason Code | Description |
|---|---|---|
| Visa | 75 | Transaction not recognized |
| Visa | 83 | Fraud card absent environment |
| Mastercard (incl. Maestro) | 37 | No cardholder authorization |
| Mastercard (incl. Maestro) | 63 | Cardholder does not recognize |
Those chargeback reasons make up the majority of all chargeback cases.
Applicability
Card Deposits/Card Verifications/Card Pre-Authorisiations with 3DS require cardholder authentication as part of the processing which means that the API parameter
initiatePaymentRequest.creationTypeID = 1(User) orinitiatePaymentRequest.creationTypeID = 11(UserInitiatedWithStoredAccount).
For Maestro a performed 3D Secure check is mandatory
Maestro Deposits must be 3D Secure checked before they can be authorized.
Successful authorization is more likely in case the Maestro card is authenticated by 3D Secure (not enrolled Maestro Cards have low success rate).
The software implementing the 3DS protocol is called Merchant Plug-in (see wikipedia.
PXP Financial PaymentService supports 2 integration scenarios for 3DS:
- The Merchant uses PXP Financial’s MPI for authentication
- The Merchant uses its own MPI for authentication
3DS in case of Redirect Integration
Please note that in case of Redirect Integration (the merchant uses PXP Financial's Hosted Payment Pages), no integration needs to be done by the merchant to apply 3D Secure.
Merchant uses PXP Financial’s MPI
PXP Financial offers its own MPI service for 3DS authentication. Merchants can use it for authenticating cardholders before the card transaction is authorized.
Merchant must implement a listener
Even though PXP Financial is providing the MPI, the merchant has to implement a listener (3DS listener) for receiving authentication results from the issuers and has to forward this information to the PXP Financial System for processing.
The following diagram illustrates the full processing flow including 3DS authentication and authorization:
3DS Enrollment Verification (step 1-4)
In this phase the enrollment status of the card is checked. The transaction is initiated with the standard initiatePayment call where one of the following additional parameters should be sent in order to activate the 3DS process:
IsThreeDSecureRequired = true: 3DS enabledIs3DSecureConditionalAvailableForPayment = true: conditional activation based on historical card data. See here for more information).
It is advisable to also include the following two parameters to achieve the best possible customer browser experience:
BrowserHeaderAccept: Content-Types that are acceptable for the response sent by the customer's browser.
E.g.BrowserHeaderAccept = text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apngBrowserHeaderUserAgent: The user agent string of the user agent.
E.g.BrowserHeaderUserAgent = Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0
The cardholder's authentication can be made mandatory, i.e. authorization for cards which are not enrolled will not be triggered, by sending an additional parameter:
ShouldAllow3DSFallback = false; default setting istrue
PXP Financial will check the enrollment status with the scheme and will return it in a standard response, see Initiate New Payment (Backend2Backend).
The merchant should persist paymentWithState.paymentID, because that will be needed to finalize the payment.
The following table lists the possible state results and their meaning:
| PaymentState (payment state ID) | Description |
|---|---|
| RedirectDataCreated (287) | The card is enrolled or the merchant chooses to allow redirection also for ADS (Activation During Shopping). PXP Financial's MPI has prepared the redirection data needed by the merchant for customer redirection to the 3DS authentication page. The merchant should continue with step 5 3DS Authentication. |
| NotEnrolledInThreeDSecure (284) | The card is not enrolled. The merchant may continue with step 12 Authorization. The chargeback liability is with the Issuer. |
| NotEnrolledInThreeDSecureADSAvailable (285) | The card is not enrolled, but "on-the-fly" enrollment is possible. This state is only returned in case the merchant has decided to not redirect the user for ADS (Activation During Shopping). The merchant may continue with step 12 Authorization. The chargeback liability is with the Merchant. |
| VerifyThreeDSecureEnrollmentErrorReported (302) | The enrollment check failed due to a scheme reported error. The merchant may continue with step 12 Authorization. The chargeback liability is with the Merchant. |
| VerifyThreeDSecureEnrollmentErrorOccurred (283) | The enrollment check failed due to a communication error or an invalid response from the scheme. The merchant may continue with step 12 Authorization. The chargeback liability is with the Merchant. |
Example initiatePaymentRequest:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<merchantTransactionID>VISA_Test</merchantTransactionID>
<paymentMethodID>2</paymentMethodID>
<amount currencyCode="EUR">10</amount>
<userID>KalixaTestUser</userID>
<userData/>
<userIP>127.0.0.1</userIP>
<userSessionID>8a957ebe-d903-4b01-8170-20dae95673a1</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>some description</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="keyBooleanValuePair">
<key>ShouldAllow3DSFallback</key>
<value>true</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderAccept</key>
<value>text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderUserAgent</key>
<value>Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0</value>
</data>
</specificPaymentData>
<paymentAccountID>VISATestAccount</paymentAccountID>
<paymentAccount>
<specificPaymentAccountData>
<data xsi:type="keyStringValuePair">
<key>CardNumber</key>
<value>4111111111111111</value>
</data>
<data xsi:type="keyStringValuePair">
<key>HolderName</key>
<value>Test</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardVerificationCode</key>
<value>111</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryMonth</key>
<value>1</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryYear</key>
<value>2025</value>
</data>
</specificPaymentAccountData>
</paymentAccount>
</initiatePaymentRequest>
Example initiatePaymentResponse:
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<paymentMethod>
<key>2</key>
<value>VISA Deposit</value>
</paymentMethod>
<merchantTransactionID>VISA_Test</merchantTransactionID>
<paymentID>cf8eed13-3f0c-4746-bb3b-afe85c143b2e</paymentID>
<userID>KalixaTestUser</userID>
<paymentProvider>
<key>92</key>
<value>CQRUK</value>
</paymentProvider>
<amount currencyCode="EUR">10</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>6850b9e5-8e69-46d5-a3b5-5d16185f7724</id>
<definition>
<key>287</key>
<value>RedirectDataCreated</value>
</definition>
<createdOn>2017-09-14T13:33:13.9434334Z</createdOn>
<description>state description</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://api.test.kalixa.com/WebMockProviders/CreditCards/3DSecure/ThreeDSecureAuthentificate.aspx?processingMode=Automatic&useStoredCertificate=false</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataTermUrl</key>
<value>https://payments.test.kalixa.com/ProviderListeners/ThreeDSecureListener.aspx</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataPaReq</key>
<value>Base64 encoded value</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataMD</key>
<value>Base64 encoded value</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataKeys</key>
<value>TermUrl,PaReq,MD</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">10</baseAmount>
<paymentDetails xsi:nil="true"></paymentDetails>
<paymentAccount>
<paymentAccountID>VISATestAccount11</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
3DS Authentication (step 5-11)
In this phase the cardholder provides his 3D Secure credentials in order to authenticate her/his identity, once the Merchant System has redirected her/him to the provided redirection URL belonging to the ACS (Access Control Server) of the issuer.
The Merchant System should redirect the customer to the URL provided in field initiatePaymentResponse.payment.state.paymentStateDetails[RedirectURL] using a POST request with additional information from the initiatePaymentResponse included:
MD: Merchant Data, used by PXP Financial to store payment specific information. Take value from:initiatePaymentResponse.payment.state.paymentStateDetails[PostDataMD]PaReq: Contains data needed by the ACS to display the authentication page. Take value from:initiatePaymentResponse.payment.state.paymentStateDetails[PostDataPaReq]TermUrl: The merchant's 3DS listenerURL, to where the customer will be redirected after he has entered his credentials. The TermUrl can be changed by the merchant if a transaction based URL is required. Take value from:initiatePaymentResponse.payment.state.paymentStateDetails[PostDataTermUrl].
After the credentials were entered by the customer, the ACS redirects the customer to the TermUrl, together with the following POST parameters:
MD: Same as in the request to ACSPaRes: Contains authentication result.
The merchant's 3DS listener must extract the above parameters from the HTTP request and pass them to the PXP Financial System by executing the executePaymentAction API method using actionId = 90 (handleThreeDSecureAuthentificationResponse).
See the example request and response below and executePaymentAction for additional information.
The PXP Financial System will validate and handle the 3DS response and will respond with an executePaymentActionResponse. The result of the 3DS authentication will be provided in actionResults.results[lastStateDefinition].
The following table lists the possible state results and their meaning:
| PaymentState (payment state ID) | Description |
|---|---|
| AuthenticatedByThreeDSecure (291) | The customer was successfully authenticated by 3DS. The merchant should continue with step 12 Authorization. The chargeback liability is with the Issuer. statusCode = 0 |
| AuthenticateByThreeDSecureAttemptsPerformed (304) | The payment is authenticated by the Issuer only (no customer authentication performed). The merchant should continue with step 12 Authorization. The chargeback liability is with the Issuer. statusCode = 0 |
| NotAuthenticatedByThreeDSecure (290) | The customer was not authenticated by 3DS. No further actions are possible. This is the final state of the payment. statusCode = 1 |
| AuthenticateByThreeDSecureFailed (305) | The ACS was not able to authenticate the payment due to an unknown error. The merchant may continue with step 12 Authorization but the chargeback liability is with the merchant. statusCode = 2 |
| AuthenticateByThreeDSecureErrorOccurred (289) | The authentication request failed due to ACS invalid response (response content validation failed, response signature check failed). No further actions are possible. This is the final state of the payment. statusCode = 1 |
| AuthenticateByThreeDSecureErrorReported (303) | The authentication request failed due to technical processing problems on the Issuer side. No further actions are possible. This is the final state of the payment. statusCode = 1 |
Example executePaymentActionRequest using actionId = 90 (handleThreeDSecureAuthentificationResponse):
<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<paymentID>cf8eed13-3f0c-4746-bb3b-afe85c143b2e</paymentID>
<actionID>90</actionID>
<actionData>
<data xsi:type="keyStringValuePair">
<key>PaRes</key>
<value>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</value>
</data>
<data xsi:type="keyStringValuePair">
<key>MD</key>
<value>X76UIbpUZSyA82uJDA/VSyonj12pBZD0/l8Up125LD39qiDk3gMQaA==</value>
</data>
</actionData>
<remark>cc pox request</remark>
</executePaymentActionRequest>
Example executePaymentActionResponse using actionId = 90 (handleThreeDSecureAuthentificationResponse):
<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<statusCode>1</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>291</value>
</result>
<result xsi:type="keyStringValuePair">
<key>CardHolderAuthenticationValue</key>
<value>MTE5ODMyNzM0MzE0NTY5NDk3Mjk=</value>
</result>
<result xsi:type="keyStringValuePair">
<key>Eci</key>
<value>05</value>
</result>
<result xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>
Card Deposit Authorization (step 12-16)
In case the merchant is not configured for automatic authorization, after authentication processing, one additional executePaymentAction call must be made, with actionID = 120 (authorize):
The PXP Financial System will submit the payment authorization request to the Card Scheme Network and will return the result of the authorization in the executePaymentActionResponse.
The following table lists the possible state results and their meaning:
| AuthorisedByProvider (13) | Successful payment. The requested amount was reserved on card for merchant.statusCode = 0 |
| RefusedByProvider (100) | The card scheme or issuer refused the payment.statusCode = 1 |
| AuthoriseErrorReportedByProvider (14) | The card scheme or issuer reported an authorization error.statusCode = 1 |
| AuthoriseCommunicationErrorOccurred (336) | Error on communication with card scheme or issuer.statusCode = 1 |
The PXP Financial System can be configured to asynchronously notify the Merchant System in the event of a successful transaction authorization but the merchant should provide a payment state changed notification listener.
Example executePaymentActionRequest using actionID = 120 (authorize):
<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<paymentID>cf8eed13-3f0c-4746-bb3b-afe85c143b2e</paymentID>
<actionID>120</actionID>
<remark>cc pox request</remark>
</executePaymentActionRequest>
Example executePaymentActionResponse using actionID = 120 (authorize):
<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<statusCode>0</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>13</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ApprovalCode</key>
<value>653006</value>
</result>
</actionResults>
</executePaymentActionResponse>
The following table provides a summary of all possible outcomes and gives a recommendation of how to deal with each case:
| Card Scheme | Enrollment Result | Authentication Result | Liability lies with | Recommended action | Corresponding state in PaymentService | Description | ECI Value |
|---|---|---|---|---|---|---|---|
| Visa | U - Unavailable | Merchant | No liability shift. Proceed to Authorisation depending on Merchant risk assessment | VerifyThreeDSecureEnrollmentErrorReported (302) | No enrollment result could be obtained. This could be due to an error in the enrollment service or a timeout. | 7 | |
| Visa | N - Not Enrolled | Issuer | Authorise payment | NotEnrolledInThreeDSecure (284) | Customer is not enrolled. Liability is shifted to Issuer | 6 | |
| Visa | ADS - Not Enrolled but Activation During Shopping available | Merchant | No liability shift. Proceed to Authorisation depending on Merchant risk assessment | NotEnrolledInThreeDSecureADSAvailable (285) | The customer is enrolled, but the merchant can decide to redirect the customer to the Issuer's enrollment page. If the merchant does not do this, liability rests with the Merchant | 6 | |
| Visa | Y - Enrolled | Y - Authentication Successful | Issuer | Authorise payment | AuthenticatedByThreeDSecure (291) | Customer is enrolled and has successfully authenticated | 5 |
| Visa | Y - Enrolled | N - Authentication Failed | Merchant | Do not authorise payment | NotAuthenticatedByThreeDSecure (290) | The customer was enrolled but used incorrect credentials | 7 |
| Visa | Y - Enrolled | A - Authentication attempted | Card Issuer | Authorise payment | AuthenticateByThreeDSecureAttemptsPerformed (304) | The isser has decided not to ask the customer to authenticate. Liabilty shifts to the Issuer. | 6 |
| Visa | Y - Enrolled | U - Authentication unavailable | Merchant | No liability shift. Proceed to Authorisation depending on Merchant risk assessment | AuthenticateByThreeDSecureFailed (305) | The customer was enrolled, but authentication could not be performed within the Issuers authentication system. | 7 |
| Visa | Y - Enrolled | E - Authentication error | Merchant | No liability shift. Because the actual authentication result is unknown, it is recommended not to proceed with authentication | AuthenticateByThreeDSecureErrorOccurred (289) AuthenticateByThreeDSecureErrorReported (303) | This means that authentication was performed, but an error happed within the issuers authentication system or PXP Financial could not interpret the reult notification for whatever reason | 7 |
| MasterCard | U - Unavailable | Merchant | No liability shift. Proceed to Authorisation depending on Merchant risk assessment | VerifyThreeDSecureEnrollmentErrorReported (302) | No enrollment result could be obtained. This could be due to an error in the enrollment service or a timeout. | 7 | |
| MasterCard | N - Not Enrolled | Issuer | Authorise payment | NotEnrolledInThreeDSecure (284) | Customer is not enrolled. Liability is shifted to Issuer | 7 | |
| MasterCard | ADS - Not Enrolled but Activation During Shopping available | Merchant | No liability shift. Proceed to Authorisation depending on Merchant risk assessment | NotEnrolledInThreeDSecureADSAvailable (285) | The customer is enrolled, but the merchant can decide to redirect the customer to the Issuer's enrollment page. If the merchant does not do this, liability rests with the Merchant | 7 | |
| MasterCard | Y - Enrolled | Y - Authentication Successful | Issuer | Authorise payment | AuthenticatedByThreeDSecure (291) | Customer is enrolled and has successfully authenticated | 2 |
| MasterCard | Y - Enrolled | N - Authentication Failed | Merchant | Do not authorise payment | NotAuthenticatedByThreeDSecure (290) | The customer was enrolled but used incorrect credentials | N/A |
| MasterCard | Y - Enrolled | A - Authentication attempted | Issuer | Authorise payment | AuthenticateByThreeDSecureAttemptsPerformed (304) | The isser has decided not to ask the customer to authenticate. If the Issuer is not participating in SecureCode OR if the issuer is participating but the customer did not enroll the card, Mastercards Attempts server will also produce this result by default | 1 |
| MasterCard | Y - Enrolled | U - Authentication unavailable | Merchant | No liability shift. Proceed to Authorisation depending on Merchant risk assessment | AuthenticateByThreeDSecureFailed (305) | The customer was enrolled, but authentication could not be performed within the Issuers authentication system. | 1 |
| MasterCard | Y - Enrolled | E - Authentication error | Merchant | No liability shift. Because the actual authentication result is unknown, it is recommended not to proceed with authentication | AuthenticateByThreeDSecureErrorOccurred (289) AuthenticateByThreeDSecureErrorReported (303) | This means that authentication was performed, but an error happed within the issuers authentication system or PXP Financial could not interpret the result notification for whatever reason | 7 |
Merchant uses its own MPI
When 3DS authentication is handled by the merchant then the following additional parameters have to be passed in initiatePaymentRequest.specificPaymentData:
ThreeDSecureCheckResult
Integer value representing the status of the check (default is 0). Possible values :
0 – NotChecked
1 – NotEnrolled
2 – Unable (corresponds to “U” value inPaRes)
3 – Attempt (corresponds to “A” value inPaRes)
4 – Authenticated (corresponds to “Y” value inPaRes)ThreeDSecureECI
String value received inecifield ofPaResThreeDSecureCAVV
Base64-encoded value received incavvfield ofPaResThreeDSecureXID
Base64 encoded value received in thexidfield ofPaRes.
During processing the values will be validated according to the following scheme:
| Method | Status | ECI | CAVV |
|---|---|---|---|
| Visa/Visa Electron | 0 (NotChecked) | [Not Passed] | [Not Passed] |
| Visa/Visa Electron | 0 (NotChecked) | 07 | [Not Passed] |
| Visa/Visa Electron | 1 (NotEnrolled) | 06 | [Not Passed] |
| Visa/Visa Electron | 2 (Unable) | 07 | [Not Passed] |
| Visa/Visa Electron | 3 (Attempt) | 06 | 28 Chars string |
| Visa/Visa Electron | 4 (Authenticated) | 05 | 28 Chars string |
| MasterCard | 0 (NotChecked) | [Not Passed] | [Not Passed] |
| MasterCard | 1 (NotEnrolled) | [Not Passed] | [Not Passed] |
| MasterCard | 2 (Unable) | [Not Passed] | [Not Passed] |
| MasterCard | 3 (Attempt) | 01 | 28 Chars string |
| MasterCard | 4 (Authenticated) | 02 | 28 Chars string |
| Maestro | 3 (Attempt) | 01 | 28 Chars string |
| Maestro | 4 | 02 | 28 Chars string |
Example initiatePaymentRequest with 3DS:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<merchantTransactionID>3654654644</merchantTransactionID>
<paymentMethodID>1</paymentMethodID>
<amount currencyCode="EUR">100</amount>
<userID>KalixaTestUser</userID>
<userData/>
<userIP>127.0.0.1</userIP>
<userSessionID>6a956eae-d903-4a01-8170-20dae92673d1</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>some description</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescriptionLanguageCode</key>
<value>de</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ThreeDSecureCheckResult</key>
<value>4</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ThreeDSecureECI</key>
<value>02</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ThreeDSecureCAVV</key>
<value>jLRabyR3C2QaABEAAFHSuWJ7w5g=</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ThreeDSecureXID</key>
<value>QXRvc0lQUyBYSUQ=</value>
</data>
</specificPaymentData>
<paymentAccountID>4765ad36-93ea-4327-a82f-767eb6f04e4d</paymentAccountID>
<paymentAccount>
<specificPaymentAccountData>
<data xsi:type="keyStringValuePair">
<key>CardNumber</key>
<value>5301250070000191</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardVerificationCode</key>
<value>111</value>
</data>
<data xsi:type="keyStringValuePair">
<key>HolderName</key>
<value>Test</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryMonth</key>
<value>1</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryYear</key>
<value>2025</value>
</data>
</specificPaymentAccountData>
</paymentAccount>
</initiatePaymentRequest>
Example initiatePaymentResponse with 3DS:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<payment>
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<paymentMethod>
<key>1</key>
<value>ECMC Deposit</value>
</paymentMethod>
<merchantTransactionID>3654654644</merchantTransactionID>
<paymentID>7dd20f99-7b2e-46ed-bbe3-501e51379831</paymentID>
<userID>KalixaTestUser</userID>
<paymentProvider>
<key>92</key>
<value>CQRUK</value>
</paymentProvider>
<amount currencyCode="EUR">100</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>7e524801-0733-4b26-8071-6fe78bdd131b</id>
<definition>
<key>13</key>
<value>AuthorisedByProvider</value>
</definition>
<createdOn>2010-12-03T17:22:25.5259063Z</createdOn>
<description>Approved or completed successfully</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ApprovalCode</key>
<value>668056</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">100</baseAmount>
<paymentDetails xsi:nil="true"></paymentDetails>
</payment>
</initiatePaymentResponse>
Smart 3D Secure
Smart 3D Secure will let the PXP Financial System decide dynamically, depending on the rules set up for/by the merchant, if 3D Secure should be used to authenticate a customer or not.
Applicability for 3DS 1.0 and 2.0
The PXP Financial Smart 3DS Logic is applied only:
- If the card which is used by a customer is NOT enrolled in 3DS 2.0
- or if the card is enrolled in 3DS 2.0 and PSD2 is not mandated (outside of Europe)
If the card is enrolled in 3DS 2.0 and PSD2 is mandated, then the Smart 3DS Logic cannot be
applied, the 3DS 2.0 check will be done in any case.
If the conditions for performing 3D Secure are met, the flow will be the same like described above in section Merchant uses PXP Financial’s MPI. If 3D Secure should not be performed, then the flow will be like for card deposits without 3D Secure.
Prererequisites for using Smart 3D Secure
- Merchant uses PXP Financial's MPI
- Merchant has specified a set of conditions when customers need to authenticate and when they do not have to authenticate
- Merchant System is passing the
IsThreeDSecureConditionalRequired = trueparameter in theinitiatePayment(for direct integration) or ingetRedirectData(for Checkout based integration).
When does it make sense to use Smart 3D Secure?
If the merchant does not want to authenticate the customer with 3D Secure on every purchase/transaction, Smart 3D Secure should be used.
For example, the merchant may require the customer to authenticate only once every 5 days, and only if the amount exceeds 50 EUR. Additionally, because some card issuers provide a bad mobile authentication experience, the merchant may decide to skip 3DS authentication for such cards.
Factors that can be used to determine the authentication experience:
- Has this card ever been successfully authenticated by this customer?
- The number of days passed since the last successful authentication of this card by this customer.
- The result of the last authentication. If the last authentication failed, the merchant will probably not allow a customer to skip 3DS under any circumstance.
- The country of the Issuing bank of the card used.
- The payment option selected by the customer (Visa, Mastercard). Please also note that a Maestro payment always needs to be authenticated.
- The Acquirer being used - this can be PXP Financial or an alternative Acquirer integrated into PXP Financial's Gateway.
- The total number of successful purchases the customer has done with this card.
- The payment amount.
- The specific BIN of the card, if such granularity is required.
- The name of the Card Issuer.
- The purchase volume of the customer in the last 24 hours, 7 days or 30 days.
- The time of day the purchase is made (maybe those purchase requests coming at 4-6 AM are slightly more suspicious?)
- The information if a customer is a VIP user.
- The date when the user has been registered in the merchant portal.
- The date when the user has made his last activity in the merchant portal.
- The type of the device which has been used by the customer.
All these parameters can be freely combined into a set of rules.
Example
For Issuer 1 with a good and intuitive 3DS authentication page, the merchant wants to ask his customers to authenticate only once every 7 days if their total purchase volume in those 7 days does not exceed 200 EUR and as long as their last authentication attempt was successful.
For Issuer 2, who has a very bad interface, the merchant wants to ask his customers to authenticate only once every 14 days, provided the amount of the transaction is not more than 20 EUR and the total volume in the last 7 days does not exceed 150 EUR.
Example initiatePaymentRequest:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<merchantID>KalixaAcceptDEMO</merchantID>
<shopID>KalixaAcceptDEMO</shopID>
<merchantTransactionID>VISA_Test</merchantTransactionID>
<paymentMethodID>2</paymentMethodID>
<amount currencyCode="EUR">10</amount>
<userID>KalixaTestUser</userID>
<userData/>
<userIP>127.0.0.1</userIP>
<userSessionID>8a957ebe-d903-4b01-8170-20dae95673a1</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>some description</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescriptionLanguageCode</key>
<value>en</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>IsThreeDSecureConditionalRequired</key>
<value>true</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>ShouldAllow3DSFallback</key>
<value>true</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderAccept</key>
<value>text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8</value>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderUserAgent</key>
<value>Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0</value>
</data>
</specificPaymentData>
<paymentAccountID>VISATestAccount</paymentAccountID>
<paymentAccount>
<specificPaymentAccountData>
<data xsi:type="keyStringValuePair">
<key>CardNumber</key>
<value>4111111111111111</value>
</data>
<data xsi:type="keyStringValuePair">
<key>HolderName</key>
<value>Test</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardVerificationCode</key>
<value>111</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryMonth</key>
<value>1</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryYear</key>
<value>2025</value>
</data>
</specificPaymentAccountData>
</paymentAccount>
</initiatePaymentRequest>
Depending on the Smart 3DS rule engine initiatePaymentResponse will contain either a payment state related to the 3DS outcome (e.g. RedirectDataCreated), or a final card deposit authorization state (AuthorisedByProvider/RefusedByProvider).
Updated 11 months ago