3DS 2.0 Pass through payments

🚧

Documentation in progress

This document will be updated with more information as it becomes available. Please ensure you revisit this page regularly to be aware of the latest changes.

Introduction

This page aims to describe the authorisation flow to merchants with a backend-to-backend integration to the PXP Financial Payment Service, but who have integrated with a third-party 3DS Server to perform 3DS 2.0 authentication.

In this scenario, the merchant need only pass through the key data elements for a 3DS 2 authorisation, unlike the full Browser-based flow for 3DS 2.0

Process Overview

A pass through 3DS 2.0 authorisation will be initiated from a merchant front-end, via a backend-to-backend call to PXP Financial after the merchant has carried out 3DS 2.0 authentication with a third-party 3DS Server and has the necessary data elements for authorisation as indicated below.

The diagram below illustrates the sequence of steps for each stage of the authentication:

912912

📘

Comparison to 3DS 1 pass through payments

3DS 2.0 pass through payment will only require additional information to be submitted in an initiatePaymentRequest.

This is similar to the 3DS 1 implementation of pass through payments which can be found here Card Deposits with 3DS

Pre-requisites

  1. You must have a test account set up for use with PXP Financial
  2. If you are an existing merchant you should already have a fully integrated backend-to-backend integration in place
  3. If you are a new merchant please refer to the Initiate New Payment (Backend2Backend) section

Integration Steps

Step 1: Create a new payment with 3DS 2 authentication data

Submit initiatePaymentRequest

The initiatePaymentRequest has been extended with new fields to support pass through 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.

The table below lists the 3DS 2.0 fields that should be obtained from your 3DS 2.0 Provider and sent in initiatePaymentRequest (API documentation about initiatePaymentRequest can be located here). These fields should be provided in initiatePaymentRequest.specificPaymentData. Please note, all fields should be provided where possible.

Field

Description

ThreeDSecureTransactionStatus

The Transaction Status value in the ARes or CRes depending on whether the authentication was frictionless or not

ThreeDSecureVersion

The 3DS 2.0 protocol version

ThreeDSecureCAVV

Corresponds to the authentication value.

ThreeDSecureECI

Electronic Commerce Indicator

DirectoryServerTransactionID

The unique ID assigned the Directory Server for this payment

📘

PSD 2 Compliance

If an exemption has been granted during authentication through another 3DS 2.0 provider, it must be flagged in the initiatePayment request.

If an exemption was requested and granted to the payment during authentication, the respective exemption ID must also be sent in ScaExemptionID field in initiatePaymentRequest.

Field

Description

ScaExemptionID

Indicates the exemption type that has been granted by Issuer for the particular transaction.
Possible values:
1- anonymousCard
2 - lowValue
3 - noExemption
4 - secureCorporate
5 - trustedBeneficiary
6 - transactionRiskAnalysis

For more information about PXP's PSD 2 Framework refer to PSD 2 Implementation Guide.

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>3DSv2_TestMerchant</merchantID>
    <shopID>3DSv2_TestShop</shopID>
    <merchantTransactionID>01eb5797-2e6b-4dd9-9938-e68a215f45ce</merchantTransactionID>
    <paymentMethodID>2</paymentMethodID>
    <amount currencyCode="EUR">10</amount>
    <userID>f9651638-2f0f-4f54-ab3f-8513ea897876</userID>
    <userData>
        <username>f9651638-2f0f-4f54-ab3f-8513ea897876</username>
        <firstname xsi:nil="true" />
        <lastname xsi:nil="true" />
        <currencyCode xsi:nil="true" />
        <languageCode xsi:nil="true" />
        <email xsi:nil="true" />
        <address xsi:nil="true" />
        <identificationNumberType xsi:nil="true" />
        <drivingLicenseNumber xsi:nil="true" />
        <drivingLicenseIssuingState xsi:nil="true" />
    </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>dc138506-2d2b-4d90-9cbb-92cf0879bd76</userSessionID>
    <creationTypeID>3</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>dd86a2f5-e53e-4a09-ab0e-1d9de6089742</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescriptionLanguageCode</key>
            <value>en</value>
        </data>
        <data xsi:type="keyIntValuePair">
            <key>PaymentProviderID</key>
            <value>92</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureTransactionStatus</key>
            <value>Y</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureCAVV</key>
            <value>MTA4NTE4NDczNDIwNDMzNjYxODM=</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureECI</key>
            <value>07</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>DirectoryServerTransactionID</key>
            <value>f7ed8582-5e38-4ff9-9271-32d804436b16</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureVersion</key>
            <value>2.1.0</value>
        </data>
    <data xsi:type="keyIntValuePair">
      <key>ScaExemptionID</key>
      <value>2</value>
    </data>
    </specificPaymentData>
    <paymentAccount>
        <specificPaymentAccountData>
            <data xsi:type="keyStringValuePair">
                <key>CardNumber</key>
                <value>4111111372680044</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>HolderName</key>
                <value>Jôe-Juán Säöüp</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>

Step 2: Process authorisation response

Receive initiatePaymentResponse

If authorisation is successful, initiatePaymentResponse is received with AuthorisedByProvider state (13).

Further details on initiatePaymentResponse can be found here
.

Example initiatePayment response:

<?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>2</key>
            <value>VISA Deposit</value>
        </paymentMethod>
        <merchantTransactionID>01eb5797-2e6b-4dd9-9938-e68a215f45ce</merchantTransactionID>
        <paymentID>ea4ccfd2-c364-45db-be56-e6d2c572f602</paymentID>
        <userID>f9651638-2f0f-4f54-ab3f-8513ea897876</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>da21b481-a3e2-466f-b284-0083b501ac41</id>
            <definition>
                <key>13</key>
                <value>AuthorisedByProvider</value>
            </definition>
            <createdOn>2019-07-02T13:07:25.1809956Z</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>357074</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">10</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ThreeDSecureVersion</key>
                <value>2.1.0</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ThreeDSecureTransactionStatus</key>
                <value>Y</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>DirectoryServerTransactionID</key>
                <value>f7ed8582-5e38-4ff9-9271-32d804436b16</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>CardholderAuthenticationVerificationValue</key>
                <value>MTA4NTE4NDczNDIwNDMzNjYxODM=</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ElectronicCommerceIndicator</key>
                <value>07</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>a1a56d61-fe3c-4a70-a88c-443e39c59b5a</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

📘

Supported Providers

Pass through payments are currently only supported for CQRUK.

We will update this page as more Providers are supported in the future.

👍

3DS 2.0 pass through payments Integration Summary

In order to integrate with PXP Financial for 3DS 2.0 pass through payments you will need to:

  • Send additional data in initiatePaymentRequest
  • Process the authorisation response as normal

Version History

Date

Description

4.07

Added example for initiatePaymentRequest and initiatePaymentResponse.

31.10

Added definition of ScaExemptionID field in relation to PSD2 framework.