5 | outline | trueThese pages describe how the merchants request Payline for an authorization coupled with a 3DS V2 authentication.
Exchanges outlines
The exchanges consist in 3
main phasesThe authentication initialization, the merchant requests Payline to initiate the authentication;- Verify enrollment which tells the merchant how authenticate the buyer for the requested order
- Challenge
The challenge handling - (optional), which represents the
merchant transferts buyer and then retrieves the authentication result;The authorization initialization, the merchant gives Payline the authentication results along with the payment attributes.This page describes the browser based authentication.
That covers the cases where the buyer is connected to the online shop using a browser within
- a desktop or laptop computer;
- a mobile application .
The app based authentication will be developped in another release of this documentation.
That covers the cases where the buyer is connected thru a mobile application using the sdk interface.
The authentication initialization
Payline dedicate the verifyEnrollment webservice to initiate the the authentication.
The ACS may require the merchant to transfert the buyer to the ACS
The challenge
The authorization
Exchanges overview
Verify Enrollment
This method tells the merchant how to authenticate the buyer according to the order he requested.
The ACS- authentication page
- Authorization
Verify Enrollment
This method tells the merchant how to authenticate the buyer according to the order he requested.
The ACS/Network may propose 3 possibilities depending on the payment card, the order and the buyer :
- to be authenticated with challenge (V2)
- authenticated in frictionless mode (V2)
- fallback in authentication V1
The merchant fills out the request with the following parameters:
- merchant transaction identifier which is the 'correlation id' used up to the authorization;
- Payment attributes (PAN, expiration, cvx, payment mode, ...);
- The URL of the system that receives the
CRes
message or Error Message; - Buyer's and order's attributes;
- The merchant indication related to the authentication. This is the way for the merchant to indicates whether a challenge is requested for this transaction.
- The browser's or the sdk's attributes of the buyer;
- The previous authentication's method of that buyer (optional);
- The result of the 3DS method (refer to the description of that use case)
In response Payline returns:
- the action to be carry out by the merchant to authenticate its buyer given by the '
returnCode
' parameter - The attributes of the call to the ACS (
HTTP_METHOD(get/post), URL, METHOD_FIELD_NAME, METHOD_FIELD_VALUE, MD_FIELD_NAME, MD_FIELD_VALUE, TERM_URL_FIELD_NAME, TERM_URL_FIELD_VALUE,...
); - The authentication result container in case of frictionless authentication
transientData
used internally by Payline to process the transaction, this field must be sent back to subsequent call to the verifyEnrollment
or doAuthorization
Processing screen requirements
EMVCo specifies that during the AReq / ARes
message cycle initiated by the call of the verifyEnrollment
web service, the merchant shall comply with the followings
Extrait |
---|
The 3DS Requestor (merchant) website shall: Seq 4.32 [Req 172] Create a Processing screen for display during the AReq/ARes message cycle. Note: The Processing screen is displayed by the 3DS Requestor website during AReq message processing. Seq 4.33 [Req 173] Display a graphical element (for example, a progress bar or a spinning wheel) that conveys to indicate to the Cardholder that processing is occurring. Seq 4.34 [Req 174] Include the DS logo for display unless specifically requested not to include. Seq 4.35 [Req 175] Not include any other design element in the Processing screen. Seq 4.36 [Req 176] Display the Processing screen for a minimum of two seconds. |
Challenge
Initiating the challenge
When the verifyEnrollment
response tells the merchant to connect the buyer to the ACS for authentication, the merchant shall
Extrait |
---|
"[Req 267] Create a 3-D Secure challenge window by generating a CReq message, creating an HTML iframe in the Cardholder browser, and generating an HTTP POST through the iframe to the ACS URL that was received in the ARes message." (EMVCo requirement) |
The merchant sets up the html form according to the response parameters of the verifyEnrollment
web service as follows
Info |
---|
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | Html code snippet of the challenge window |
---|
|
|
collapsetrue | <!--...-->
<iframe id="<iFrameId>" name="<iFrameName>" style="width: <width>; height: <height>;" src="javascript:false;" xmlns="http://www.w3.org/1999/xhtml">
<!--...-->
</iframe>
<!--...-->
<form id="webform0" name="" method="<HTTP_METHOD>" action="<URL>" accept_charset="UTF-8" target="<iFrameName>">
<input type="hidden" name="_charset_" value="UTF-8"/>
<input type="hidden" name="<METHOD_FIELD_NAME>" value="<METHOD_FIELD_VALUE>"/>
<input type="hidden" name="<MD_FIELD_NAME>" value="<MD_FIELD_VALUE>"/>
<input type="hidden" name="<TERM_URL_FIELD_NAME>" value="<TERM_URL_FIELD_VALUE>"/>
</form>
<!--...--> |
|
Info |
---|
title | Authentication window design hints |
---|
|
The merchant designs the authentication window taking into account that the pre-configured sizes in pixels of the authentication windows the ACS shall renders are as follows (width x height): 250 x 400 390 x 400 500 x 600 600 x 400 Full screen
The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. (EMVCo requirement) |
Handling the challenge response
The consumer returns from the authentication to the <TERM_URL_FIELD_VALUE>
that was included in the form. When the consumer returns, two parameters will be included: <MD_FIELD_NAME>
and 'PaRes
' or 'CRes
'.
<MD_FIELD_NAME>
contains the same reference number sent to the ACS. Should be used to look up the correct transaction in the merchant's system.PaRes
or CRes
contains the Payment Authentication Response that must be sent in to the doAuthorization
web service.
Authorization
To issue an authorization request after the buyer has been 3DS authenticated, the merchant shall fill out the following fields of the authentication3DSecure
object:
md
pares
if the ACS requested a challengeresultContainer
if the ACS processed the authentication in frictionless mode
Avertissement |
---|
The cardBrand (ie. scheme) in the doAuthorizaton must be the same as in the authentication |
Authentification <verifyEnrollmentRequestAuthentication use cases
The merchant begins the authentication process by sending a verifyEnrollmentRequest
to Payline.
The message's snippet below explains how to fill up that request.
Bloc de code |
---|
language | xml |
---|
title | verifyEnrollmentRequest |
---|
|
collapse | true |
---|
<soapenv:Envelope xmlns:soapenv="http:// |
implws.payline.experian.comxmlsoap.org/soap/envelope/" xmlns: |
ns2objimpl.ws.payline.experian.com" xmlns: |
soapschemas.xmlsoap.org/soap/envelope/"> obj.ws.payline.experian.com">
<soapenv:Header/>
<soapenv:Body>
<ns1:verifyEnrollmentRequest>
<ns1: |
version>22<
<ns1:card>the latest version number -->
<ns1:mdFieldValue></ns1:mdFieldValue> |
<ns2:number>453304XXXXXX8423</number> <!-- merchant transaction identifier which is the 'correlation id' wiht the later web service calls -->
|
<ns2:type>VISA</ns2:type>
<ns2:expirationDate>0319</expirationDate> <!-- May be let empty, in this |
case, Payline will return |
<ns2:cvx xsi:nil="true"/> the md value to be given in the authorization -->
|
<ns2:ownerBirthdayDate/>
<ns2:password/>
<ns2:cardPresent/>
</ns1:card>
<ns1:payment> <!-- The URL of the merchant that receives the CRes message or Error Message (V2) -->
|
<ns2:amount>16230</ns2:amount>
<ns2:currency>978</ns2:currency><ns1:returnURL>https://merchant.com/notification/3DSresult.do?orderId=47960539</ns1:returnURL>
<ns1:threeDSInfo>
<ns2: |
action>100<action>
<ns2:mode>CPT</ns2:mode>
<ns2:contractNumber>CB_3DS</ns2:contractNumber>
<ns2:differedActionDate xsi:nil="true"/>
<ns2:method xsi:nil="true"/>
<ns2:softDescriptorxsi:nil="true"/>
<ns2:cardBrand xsi:nil="true"/><!-- Optional: This is the way for the merchant to indicates whether a challenge is requested for this transaction. -->
|
<!-- Optionnal;bydefault:schemedefinedinthePaylinePaymentmethodcontract-->
<ns2:registrationTokenxsi:nil="true"/>
</ns1:payment>
<ns1:order> <!-- optional information about the 3DS cardholder previous authentication. -->
<ns2:threeDSReqPriorAuthData/> <!-- For future usage -->
<ns2:threeDSReqPriorAuthMethod>02</ns2:threeDSReqPriorAuthMethod>
<ns2 |
:ref>47960539<:threeDSReqPriorAuthTimestamp>12/01/2017 11:59:00</ns2: |
ref>threeDSReqPriorAuthTimestamp>
<ns2: |
origin xsi:nil="true"/>
<ns2:country>FR</ns2:country>
<ns2:taxesxsi:nil="true"/>
<ns2:amount>16230</ns2:amount>
<ns2:currency>978</ns2:currency>
<ns2:date>27/01/201911:01</ns2:date>
<ns2:detailsxsi:nil="true"/>
<ns2:deliveryTime>6</ns2:deliveryTime> <!-- mandatory for browser based |
<!Stronglyrecommendedforfrictionless.(samedaydhipping,overnight shipping, <ns2:acceptHeader> xyz.... |
-->
tre </ns2:acceptHeader>
<ns2: |
deliveryMode>7<deliveryMode>javaEnabled>
<ns2:language>fr</ns2:language>
<ns2:colorDepth>32</ns2:colorDepth>
|
<!--Stronglyrecommendedforfrictionless --> <ns2:screenHeight>420</ns2:screenHeight>
|
<ns2:screenWidth>400</ns2:screenWidth>
<ns2:timeZoneOffset>-120</ns2:timeZoneOffset>
<ns2:javascriptEnabled>Y</ns2:javascriptEnabled>
<ns2:userAgent>Mozilla/5.0 (Windows NT 6.1; WOW64; rv:64.0) Gecko/20100101 Firefox/64.0</ns2:userAgent>
</ns2:browser>
<ns2:sdk/>
|
<!--Shiptocardholder’sbillingaddress,lockerdelivery,traveloreventticket,...-->
<ns2:deliveryExpectedDatexsi:nil="true"/>Incase pre-order the merchant that receives the 3DS method result -->
<ns2: |
deliveryExpectedDelay xsi:nil="true"/>
<ns2:deliveryCharge>2490</ns2:deliveryCharge>
<ns2:orderExtended>
<ns2:giftCardAmount>0</ns2:giftCardAmount> threeDSMethodNotificationURL>https://merchant.com/3DSMethodNotif?threeDSSessionData=2F04CC56F968373D0114AD4B6BB4E4F1 </ns2:threeDSMethodNotificationURL>
<ns2:threeDSMethodResult>I</ns2:threeDSMethodResult> <!-- |
Ifgiftcardsareusedpayment,partialor not giftCardCount>0<challengeWindowSize>04</ns2: |
giftCardCount>challengeWindowSize> <!-- Default size is 03 |
<!--Ifgiftcardsareusedforpayment,partialornot-->
<ns2:reorderIndicator>01</ns2::reorderIndicator><!--Indicateswhetherthecardholderisreorderingpreviouslypurchasedmerchandise -->
</ns1:threeDSInfo>
<ns1:card>
<ns2:number>4970105191919195</ns2:number> |
<!--Stronglyrecommendedforfrictionless-->
/ns2:orderExtended>
</ns1:order>
<ns1:buyer>
<ns2:title>4</ns2:title>
<ns2:lastName>Dupont</ns2:lastName>!--+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-->
<ns2:encryptionKeyId></ns2:encryptionKeyId> |
Stronglyrecommended for frictionless of number,(encryptionKeyId, encryptedData) or token +-->
<ns2: |
firstName>Jean<firstName> Strongly recommended for frictionless -->
<ns2:email>jean.dupont@monext.net</ns2:email> <!--Stronglyrecommendedforfrictionless-->
<ns2:shippingAdress> <!-- Strongly recommended for frictionless title>4<title><!--Stronglyrecommendedforfrictionless-->
<ns2:name xsi:nil="true"/>
<!--+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-->
<ns2: |
createDate>05/112011</createDate><!--Stronglyrecommendedforfrictionless-->
<ns2:firstName>Jean</ns2:firstName>
<ns2:expirationDate>0323</ns2:expirationDate> |
<!--Stronglyrecommendedforfrictionless-->
<ns2:lastName>Dupont</ns2:lastName><!--Stronglyrecommendedforfrictionless-->
<ns2:street1>260,rueClaudeNicolasLedoux</ns2:street1>Strongly recommended for frictionless
<ns2:street2>CS60507</ns2:street2>
<ns2:ownerBirthdayDate/>
<ns2:password/>
<ns2:cardPresent/>
</ns1:card>
<ns1:payment> |
<!--Stronglyrecommendedforfrictionless-->
<ns2:cityName>Aix-en-Provencecedex3</ns2:cityName><!--Stronglyrecommendedforfrictionless-->
<ns2:zipCode>13593</ns2:zipCode>
<ns2:amount>16230</ns2:amount>
<ns2:currency>978</ns2:currency>
<ns2:action>100</ns2:action>
|
<!-- Strongly recommended for frictionless --> country>FR<contractNumber>11111111111</ns2: |
country>contractNumber>
<ns2:differedActionDate/>
|
<ns2:method/>
<ns2:softDescriptor/>
<ns2:cardBrand/> <!-- |
Strongly recommended for frictionless optional; by default: scheme defined in the Payline Payment method contract -->
<ns2:registrationToken/>
|
<ns2:email><ns2email><!--Incaseofdigitalgoodsendedbyemail;Stronglyrecommendedforfrictionless-->
<ns2:phone>0442251515</ns2:phone>
state>13<state> county xsi:nil="true"/> phoneType xsi:nil="true"/></ns2:shippingAdress><ns2:taxes/>
<ns2:amount>16230</ns2: |
billingAddress> title>4<title> name xsi:nil="true"/>date>27/01/2019 11:01</ns2:date>
|
firstName>Jean<ns2:firstName> lastName>Dupont<lastName>
<ns2:street1>260,rueClaudeNicolasLedoux</ns2:street1> <!-- Strongly recommended for frictionless |
-->
<ns2:street2>CS 60507</ns2:street2> . (same day dhipping,overnight shipping, ... -->
<ns2:deliveryMode>7</ns2:deliveryMode> <!-- Strongly recommended for frictionless -->
|
<ns2:cityName>Aix-en-Provencecedex3</ns2:cityName><!--Stronglyrecommendedforfrictionless-->
<ns2:zipCode>13593</ns2:zipCode> <!-- Ship to cardholder’s billing address, locker |
<!-- Strongly recommended for frictionlessdelivery, travel or event ticket, ... -->
|
country>FR<ns2:country> of pre-order -->
<ns2:deliveryExpectedDelay/>
<ns2:deliveryCharge>2490</ns2:deliveryCharge>
<ns2:orderExtended>
<ns2:giftCardAmount>0</ns2:giftCardAmount> |
<!--Stronglyrecommendedforfrictionless-->
<ns2:phone>0442251515</ns2:phone> <!-- If gift cards are used for payment, partial or not -->
<ns2:giftCardCount>0</ns2:giftCardCount> <!-- |
Strongly recommended If gift cards are used for |
frictionlesspayment, partial or not -->
<ns2: |
state>13<reorderIndicator>01</ns2: |
state>
<ns2:county xsi:nil="true"/>
<ns2:phoneType xsi:nil="true"/>
</ns2:billingAddress>
<ns2:accountCreateDate>05/11/11</ns2:accountCreateDate> <!-- Indicates whether the cardholder is reordering previously purchased merchandise -->
|
<!--Stronglyrecommendedforfrictionless-->
<ns2:accountAverageAmountxsi:nil="true"/>
<ns2:accountOrderCount>0</ns2:accountOrderCount>
<ns2:walletIdxsi:nil="true"/>
<ns2:walletDisplayed xsi:nil="true"/ <!-- Strongly recommended for frictionless -->
|
<ns2:walletSecured xsi:nil="true"/></ns2:orderExtended>
</ns1:order>
<ns1:buyer>
<ns2: |
walletCardInd xsi:nil="true"/>title>4</ns2:title>
<ns2: |
ip>90.37.101.225<ip>mandatoryifbrowserbased authentication -->
<ns2:firstName>Jean</ns2:firstName> |
<ns2:mobilePhone>0627720695</ns2:mobilePhone>
<ns2:customerId>4805157</ns2:customerId>legalStatus>1<email>jean.dupont@monext.net</ns2: |
legalStatus>
<ns2:legalDocumentxsi:nil="true"/>
<ns2:birthDate xsi:nil="true"/>
<ns2:fingerprintID xsi:nil="true"/ <!-- Strongly recommended for frictionless -->
<ns2: |
deviceFingerprint xsi:nil="true"/>
<ns2:isBotxsi:nil="true"/>
<ns2:isIncognitoxsi:nil="true"/>
<ns2:isBehindProxy xsi:nil="true"/>
<ns2:isFromTorxsi:nil="true"/>
<ns2:isEmulatorxsi:nil="true"/>
<ns2:isRootedxsi:nil="true"/>
<ns2:hasTimezoneMismatch xsi:nil="true"/>
<ns2:merchantAuthentication><!-- Strongly recommended for frictionless -->
|
method>02<method><Recommendedrecommended for frictionless -->
<ns2:name/>
<ns2: |
date>2701/2019 12:01<date> createDate> <!-- Strongly |
Recommendedrecommended for frictionless -->
|
< <ns2:firstName>Jean</ns2: |
merchantAnthentication>
<ns2:buyerExtended><ns2:buyerExtendedHistory> <!--Stronglyrecommendedforfrictionless-->
<ns2:suspiciousActivity>01</ns2:suspiciousActivity> <!-- Strongly recommended for frictionless --> |
<ns2:lastName>Dupont</ns2:lastName> <!-- Strongly recommended for frictionless -->
<ns2:street1>260, rue Claude |
Nicolas Ledoux</ns2:street1> |
Indicateswhetherthe merchant has experienced suspicious activity
<ns2:street2>CS 60507</ns2:street2> <!-- Strongly recommended for frictionless -->
<ns2:cityName>Aix-en-Provence cedex 3</ns2:cityName> |
(includingpreviousfraud)on the cardholder account. lastChange>07/12/2018 10:40</lastChange><!--Datethatthecardholder’saccountwiththemerchantwaslastchanged-->
<ns2:lastPasswordChange>07/12/201810:40</ns2:lastPasswordChange>Datethatcardholder’saccount with the merchant frictionless -->
<ns2:country>FR</ns2:country> <!-- Strongly recommended for frictionless -->
<ns2:email></ns2:email> <!-- |
had a password change or account reset. In case of digital good sended by email; Strongly recommended for frictionless -->
|
orderCount6Months>15<orderCount6Months>phone>
<ns2:state>13</ns2:state>
<ns2:county/>
<ns2:phoneType/>
|
<!-- Number of purchases with this cardholder account during
</ns2:shippingAdress>
<ns2:billingAddress>
<ns2:title>4</ns2:title>
<ns2:name/>
<ns2:firstName>Jean</ns2:firstName>
<ns2:lastName>Dupont</ns2:lastName>
<ns2:street1>260, rue Claude Nicolas Ledoux</ns2:street1> <!-- Strongly recommended for frictionless -->
<ns2:street2>CS 60507</ns2:street2> <!-- |
theprevioussixmonths.-->
<ns2:cityName>Aix-en-Provence cedex |
<ns2:provisionAttemptsDay>0<provisionAttemptsDay>NumberofAdd Card attempts in the last 24 hours. transactionCountDay>0<transactionCountDay><!--Numberoftransactions(successfulandabandoned)forthiscardholder-->
<!-- Strongly recommended for frictionless -->
<ns2:country>FR</ns2:country> <!-- Strongly recommended for frictionless -->
<ns2:phone>0442251515</ns2:phone> |
<!-- account with the merchant across all payment accounts in the previous 24hours.-->
<ns2:transactionCountYear>38</ns2:transactionCountYear>Number of transactions (successful and abandoned)this cardholderfrictionless -->
<ns2:state>13</ns2:state>
<ns2:county/>
<ns2:phoneType/>
</ns2:billingAddress>
<ns2:accountCreateDate>05/11/11</ns2:accountCreateDate> <!-- Strongly recommended for frictionless -->
<ns2:accountAverageAmount/>
<ns2:accountOrderCount>0</ns2:accountOrderCount>
<ns2:walletId/>
<ns2:walletDisplayed/>
<ns2:walletSecured/>
<ns2:walletCardInd/>
<ns2:ip>90.37.101.225</ns2:ip> |
<!--accountwiththe3DSRequestoracrossallpaymentaccountsinthepreviousyear.-->
<ns2:paymentAccountAge>14/11/2018</ns2:paymentAccountAge>Datethatthepaymentaccountwasenrolled in the -->
<ns2:mobilePhone>0627720695</ns2:mobilePhone>
<ns2:customerId>4805157</ns2:customerId>
<ns2:legalStatus>1</ns2:legalStatus>
<ns2:legalDocument/>
<ns2:birthDate/>
<ns2:fingerprintID/>
<ns2:deviceFingerprint/>
<ns2:isBot/>
<ns2:isIncognito/>
<ns2:isBehindProxy/>
<ns2:isFromTor/>
<ns2:isEmulator/>
<ns2:isRooted/>
<ns2:hasTimezoneMismatch/>
<ns2:merchantAuthentication>
|
<!--cardholder’s account with the merchant. -->
</ns2:buyerExtendedHistory></ns2:buyerExtended>
</ns1:buyer>
<ns1:subMerchant xsi:nil="true"> <ns2:method>02</ns2:method> <!-- Recommended for frictionless -->
|
<ns1:userAgent/><ns2:date>27/01/2019 12:01</ns2:date> <!-- Recommended for frictionless -->
</ns2:merchantAuthentication>
<ns2:buyerExtended><ns2:buyerExtendedHistory> <!-- Strongly recommended for frictionless -->
|
<ns2:suspiciousActivity>01</ns2:suspiciousActivity> <!-- Strongly recommended for frictionless -->
|
<!-- Deprecated, usebrowser.userAgentinstead-->
<!-- Indicates whether the merchant has experienced suspicious activity -->
|
<!--TheURLofthesystemthatreceivestheCResmessageorErrorMessage-->
<ns1:returnURL>https://merchant.com/notification/3DSresult.do;orderId=47960539</ns1:returnURL>
<ns1:threeDSInfo>
<ns2:challengeInd>02</ns2:challengeInd><Optional:Thisiswayfor the merchant to indicates whether a challenge is requested for this transaction. -->
account. -->
<ns2:lastChange>07/12/2018 10:40</ns2:lastChange> <!-- Date that the cardholder’s account with the merchant was last changed -->
<ns2:lastPasswordChange>07/12/2018 10:40</ns2:lastPasswordChange> <!-- Date that cardholder’s account with the merchant -->
|
<!--optionalinformationabouta3DS cardholder authentication that occurred prior to the current transaction. -->
<ns2:threeDSReqPriorAuthData/> For future usage had a password change or account reset. -->
<ns2: |
threeDSReqPriorAuthMethod>02<orderCount6Months>15</ns2: |
threeDSReqPriorAuthMethod>
<ns2:threeDSReqPriorAuthTimestamp>12/01/2017 11:59</ns2:threeDSReqPriorAuthTimestamp>
purchases with this cardholder account during -->
|
<ns2:browser> mandatoryforbrowserbasedauthentication acceptHeader> xyz....tre <provisionAttemptsDay>0</ns2: |
acceptHeader>provisionAttemptsDay> <!-- Number of Add Card attempts in the last 24 hours.-->
<ns2:transactionCountDay>0</ns2:transactionCountDay> |
<ns2:javaEnabled>true</ns2:javaEnabled> <!-- Number of transactions (successful and abandoned) for this cardholder -->
|
<ns2:language>fr</ns2:language> <!-- account with the merchant across all payment accounts in the previous 24 |
colorDepth>32<transactionCountYear>38</ns2: |
colorDepth>transactionCountYear> <!-- Number of transactions (successful and abandoned) for this cardholder -->
|
<ns2:screenHeight>420</ns2:screenHeight>
<!-- account with the 3DS Requestor across |
<ns2:screenWidth>400</ns2:screenWidth> all payment accounts in the previous year. -->
<ns2:paymentAccountAge>14/11/2018</ns2:paymentAccountAge> <!-- Date that the payment account was enrolled in the |
<ns2:timeZoneOffset>+60</ns2:timeZoneOffset>
<ns2:javascriptEnabled>true</ns2:javascriptEnabled> <!-- cardholder’s account with the merchant. -->
</ns2:buyerExtendedHistory></ns2:buyerExtended>
</ns1:buyer>
<ns1:subMerchant/> |
<ns2:userAgent>Mozilla/5.0(WindowsNT6.1;WOW64;rv:64.0)Gecko/20100101Firefox/64.0</ns2:userAgent>
</ns2:browser>
<ns2sdk
<!-- in case the ACS requires the 3DS method -->
<ns2:threeDSMethodNotificationURL>https://merchant.com/3DSMethodNotif;threeDSSessionData=2F04CC56F968373D0114AD4B6BB4E4F1 </ns2:threeDSMethodNotificationURL>
<ns2:threeDSMethodResult>I</ns2:threeDSMethodResult> <!-- Shall be set up to 'I' for the first verifyEnrollment call-->
</ns1:threeDSInfo>
<ns1:mdFieldValue>60c19577-b902-43b9-9033-2eb366551228<ns1:mdFieldValue> <!-- merchant transaction identifier which is the 'correlation id' used up to the authorization -->
<!-- Deprecated, use browser.userAgent instead -->
|
<ns1:transientData></ns1:transientData> <!-- |
May be let empty, in this case, Payline will return the md value to be given in the authorization --> required if present in the response of previous calls -->
<ns1:merchantScore/> <!-- For CB scoring only -->
<ns1:walletId/> |
<ns1:transientData>{JSON}</ns1:transientData><!--requiredifpresentintheresponseofpreviouscalls-->merchantScore<!--For CB scoring only -->
<ns1:walletId/> <ns1:generateVirtualCvx/> |
<ns1:walletCardInd/> </ns1:verifyEnrollmentRequest>
|
<ns1:generateVirtualCvx/> ns1verifyEnrollmentRequest> The returnCode present in the verifyEnrollmentResponse
message tells the merchant how to continue:
03101
: The ACS requires a challenge to authenticate the buyer
(eg. description)- description
03102
: The ACS authenticated the buyer in frictionless mode
(eg. )03000
: The buyer shall authenticated using 3DS V1
(eg. )03100
: The ACS requires the 3DS Method to be called
(eg. )03103: Ancre |
---|
| AUTH_WITH_CHALLENGE |
---|
| AUTH_WITH_CHALLENGE |
---|
|
Authentification diagramDisplayNameAuthentication with challenge
zoom | 1 |
---|
diagramName | challengeFlow.drawio |
---|
|
lboxtruecontentVer1revision2diagramNamediagramDisplayName | challengeFlow.drawio |
---|
|
simpleViewerfalsewidth737linkstbstylediagramWidth | 737 |
---|
height | 441
The merchant receives the following verifyEnrollmentResponse
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | Authentication with challenge |
---|
|
collapse | true |
<impl:verifyEnrollmentResponse xmlns:impl="http://impl.ws.payline.experian.com" xmlns:obj="http://obj.ws.payline.experian.com">
<impl:result>
<obj:code>03101</obj:code> <!-- The ACS requires a challenge -->
<obj:shortMessage>ACCEPTED</obj:shortMessage>
<obj:longMessage>Transaction accepted - Challenge requested</obj:longMessage>
</impl:result>
<!------------------------------ Attributes for the CReq message Beginning -->
<impl:actionUrl>https://dsx.modirum.com:443/dstests/ACSEmu2</impl:actionUrl>
<impl:actionMethod>POST</impl:actionMethod>
<impl:pareqFieldName>creq</impl:pareqFieldName>
<impl:pareqFieldValue>ewogICAiYWNzVHJhbnNJRCIgOi......jIgp9</impl:pareqFieldValue>
<impl:mdFieldName>MD</impl:mdFieldName>
<impl:mdFieldValue>CixYXysxxvCVaEvolWXq</impl:mdFieldValue>
<!------------------------------ Attributes for the CReq message End-->
<mpiResult>C</mpiResult>
<authentication3DSecure\>
<transientData>{JSON}</transientData> <!-- Important : must be sent in subsequent calls -->
</impl:verifyEnrollmentResponse> |
The merchant creates a 3-D Secure challenge window by generating a CReq
message, creating an HTML iframe in the Cardholder browser, and generating an HTTP POST
through the iframe to the ACS URL that was received in the ARes
message."
The window contains :
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | Html code snippet of the challenge window |
---|
|
collapse | true |
---|
<!--...-->
<iframe id="idIframeChallenge" name="challenge" style="width: 390; height: 400;" src="javascript:false;" xmlns="http://www.w3.org/1999/xhtml">
<!--...-->
</iframe>
<!--...-->
<form id="webform0" name="" method="POST" action="https://localhost.modirum.com:8543/dstests/ACSEmu2" accept_charset="UTF-8" target="challenge">
<input type="hidden" name="_charset_" value="UTF-8"/>
<input type="hidden" name="creq" value="ewogICAiYWNzVHJhbnNJRCIgOi....lmLTgwMDAtMDAwMDAwMDJmYTk5Igp9"/>
</form>
<!--...--> |
When the buyer is done with the authentication, the merchant retrieves the CRes
message base64 encoded posted by the ACS to the termURL
.
Ancre |
---|
| FRICTIONLESS_AUTH |
---|
| FRICTIONLESS_AUTH |
---|
|
Frictionless authentication Diagramme draw.io |
---|
| |
---|
diagramName | frictionlessFlow.drawio |
---|
simpleViewer | false |
---|
width | 727 |
---|
|
linkstbstyle | diagramDisplayName | frictionlessFlow.drawio |
---|
lbox | true |
---|
contentVer | 1 |
---|
height | 361 |
---|
revision | 1 |
---|
|
The merchant receives the following verifyEnrollmentResponse
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | Frictionless authentication |
---|
|
collapse | true |
---|
<impl:verifyEnrollmentResponse xmlns:impl="http://impl.ws.payline.experian.com" xmlns:obj="http://obj.ws.payline.experian.com">
<impl:result>
<obj:code>03102</obj:code> <!-- The ACS accept a frictionless -->
<obj:shortMessage>ACCEPTED</obj:shortMessage>
<obj:longMessage>Transaction accepted - Cardholder authenticated</obj:longMessage>
</impl:result>
<impl:mdFieldName>MD</impl:mdFieldName>
<impl:mdFieldValue>JikRUglPzWGYfPllKpPW</impl:mdFieldValue>
<impl:mpiResult>Y</impl:mpiResult>
<impl:authentication3DSecure>
<obj:resultContainer>eyJjb250YWluZXJWZXJzaW9uIjoiMSIsIm.....W9uIjoiMi4xLjAifQ==</obj:resultContainer>
</impl:authentication3DSecure>
<transientData>{JSON}</transientData> <!-- must be sent in subsequent call -->
</impl:verifyEnrollmentResponse> |
Ancre |
---|
| V1_FALLBACK_AUTH |
---|
| V1_FALLBACK_AUTH |
---|
|
3DS V1 fallback Diagramme draw.io |
---|
| |
---|
diagramName | V1Fallback.drawio |
---|
simpleViewer | false |
---|
width | 774 |
---|
|
linkstbstyle | diagramDisplayName | V1Fallback.drawio |
---|
lbox | true |
---|
contentVer | 4 |
---|
height | 401 |
---|
revision | 1 |
---|
|
The merchant receives the following verifyEnrollmentResponse
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | Authentication with challenge |
---|
|
collapse | true |
<verifyEnrollmentResponse xmlns="http://impl.ws.payline.experian.com" xmlns:obj="http://obj.ws.payline.experian.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<result>
<obj:code>03000</obj:code> <!-- The ACS requires a fallback in 3DS V1 -->
<obj:shortMessage>ACCEPTED</obj:shortMessage>
<obj:longMessage>Transaction accepted</obj:longMessage>
</result>
<!------------------------------ Attributes for the Pareq message Beginning -->
<actionUrl>https://ssl-prd-u7f-fo-acs-pa-casa.wlp-acs.com/acs-pa-service/pa/paRequest</actionUrl>
<actionMethod>POST</actionMethod>
<pareqFieldName>PaReq</pareqFieldName>
<pareqFieldValue>eJxVUl1vgjAU/SvG99EPaAVzbeJwycyCOpQl28vC...GUY8y9ux4x1+U2M9F3PcY9MxES7HX2BgAyLqh/VdQ/vK7+fYhfHAOuMA==</pareqFieldValue>
<termUrlName>TermUrl</termUrlName>
<termUrlValue>https://merchant.fr/authentV1Result</termUrlValue>
<mdFieldName>MD</mdFieldName>
<mdFieldValue>60c19577-b902-43b9-9033-2eb366551228</mdFieldValue>
<!------------------------------ Attributes for the PaReq message End-->
<mpiResult>Y</mpiResult>
<virtualCvx></virtualCvx>
<token></token>
<authentication3DSecure\>
<transientData>{JSON}</transientData> <!-- must be sent in subsequent call -->
</verifyEnrollmentResponse> |
The merchant acts as for a regular 3DS V1 authentication.
The merchant creates a 3-D Secure authentication window by generating a PaReq
message.
When the buyer is done with the authentication, the merchant retrieves the PaRes
message base64 encoded posted by the ACS to the termURL.
Authentication's exception handlingReturn code | Meaning | Action to be taken |
---|
03001 | The bin card range not taken into account by any ACS. |
Up to the merchant continuing with the authorization or to refuse and request for another card.
|
03002 | The ACS handling the bin card range doésn't know the cardholder |
03003 | Athentication refused | Refer to the transstatusInfo present in the resultContainer to determine the cause of refusal and adapt the response. |
03006 | Invalid Pares | The authentication response message given by the merchant has been altered. |
03007 | Technical error on the ACS side | Refer to the transstatusInfo present in the resultContainer to determine the cause of refusal and adapt the response. |
03008 | Authentication attempted | Due to an incident the ACS doesn't finalize the authentication but certifies the authentication has been issued by the merchant. According the trust levef of the transaction, the merchant may either refuse the payment or issue the authorization Request. |
All other return code or no response | Payline technical error | 03009 | 3DS technical error | Monext Online might have encountered some transient technical issue. If raised in integration phase the most probable cause is a not well formed webservice message (verify all the mandatory parameters are present) |
03103 | Mandatory parameter missing | Add the value of the mandatory parameters (refer to the web service description) |
All other return code or no response | Payline technical error | According the trust levef of the |
According the trust levef of the transaction, the merchant may either refuse the payment or issue an authorization Request with authentication exemption due to technical outage doAuthorizationRequest with authentication3DSecure.pares parameter set to '3DS_UNAVAILABLE' |
Error during the challenge
Error | Meaning | Action to be taken |
---|
The merchant doesn't receive the challengeResponse message | Network error or ACS error | According the trust levef of the transaction, the merchant may either refuse the payment or issue an authorization Request with authentication exemption due to technical outage doAuthorizationRequest with authentication3DSecure.pares parameter set to '3DS_UNAVAILABLE' |
3DS error during the authorization
Error | Meaning | Action to be taken |
---|
03006 03022 | Authentication result cannot be retrieve. | According the trust levef of the transaction, the merchant may either refuse the payment or issue an authorization Request with authentication exemption due to technical outage doAuthorizationRequest with authentication3DSecure.pares parameter set to '3DS_UNAVAILABLE' |
|
|
|
Ancre |
---|
| UC-3DS_METHOD |
---|
| UC-3DS_METHOD |
---|
|
The ACS requires the 3DS Method to be calledThe ACS may require that before anything the buyer's browser to be redirected to it.
Diagramme draw.io |
---|
| |
---|
diagramName | 3DSMethod.drawio |
---|
simpleViewer | false |
---|
width | 576 |
---|
|
links | tbstyle | diagramDisplayName | 3DSMethod.drawio |
---|
lbox | true |
---|
contentVer | 2 |
---|
height | 421 |
---|
revision | 1 |
---|
|
In that case, Payline renders a returnCode
set to 03100
.
The merchant receives the following verifyEnrollmentResponse
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | ACS requires the 3DS method to be called |
---|
|
collapse | true |
<impl:verifyEnrollmentResponse xmlns:impl="http://impl.ws.payline.experian.com" xmlns:obj="http://obj.ws.payline.experian.com">
<impl:result>
<obj:code>03100</obj:code> <!-- The ACS requires the 3DS method to be called -->
<obj:shortMessage>ACCEPTED</obj:shortMessage>
<obj:longMessage>3DS method requested before enrollment</obj:longMessage>
</impl:result>
<!------------------------------ Attributes for the 3DS Method Beginning -->
<impl:actionUrl>https://dsx.modirum.com/dstests/ACSEmu2?handshake=1</impl:actionUrl>
<impl:actionMethod>post</impl:actionMethod>
<impl:pareqFieldName>threeDSMethodData</impl:pareqFieldName>
<impl:pareqFieldValue>eyAidGhy.......NvbSIgfQ</impl:pareqFieldValue>
<impl:mdFieldName>MD</impl:mdFieldName>
<impl:mdFieldValue>bJZgiqZulMTZCrKyOzJn</impl:mdFieldValue>
<!------------------------------ Attributes for the 3DS Method End-->
<transientData>{JSON}</transientData> <!-- Important : must be sent in subsequent call -->
</impl:verifyEnrollmentResponse> |
The merchant renders a hidden HTML iframe in the Cardholder browser and sends a form with a field named threeDSMethodData
.
The merchant constructs the iframe for the 3DS method in a very similar way than for the challenge.
The window contains :
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | Iframe code snippet for the 3DS method |
---|
|
collapse | true |
<!--...-->
<iframe id="idIframe3DSMethod" name="threeDSMethod" style="width: 0; height: 0; style="visibility: hidden;" src="javascript:false;" xmlns="http://www.w3.org/1999/xhtml">
<!--...-->
</iframe>
<!--...-->
<form id="webform0" name="" method="POST" action="https://nspk-ds.test.modirum.com/ds/DDF/1" accept_charset="UTF-8" target="threeDSMethod">
<input type="hidden" name="_charset_" value="UTF-8"/>
<input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDo...JbTdFdjJYTmkwNnh6YmZNJTJGR3MlM0QiIH0"/>
</form>
<!--...--> |
After having redirected the buyer's browser iframe to the ACS, the merchant wait for the notification of the completion of the 3DS method.
The ACS POST to the result to threeDSInfo
.
threeDSMethodNotificationURL
parameter of the verifyEnrollmentRequest
.
If the merchant receives the notification within the next 10 secondes he issues a second time the verifyEnrollmentRequest
after having
added set adds updates the threeDSMethodResult
parameter set to 'N
' in the second verifyEnrollmentRequest
.
Authorization
New Request data
When the authentication process is done the merchant issues a doAuthorizationRequest message enhanced with the result of the authentication.
Request fields updates
In order to handle 3DS , new fields are required in Authorization
Payline Field Name | Format | Mandatory | Comment |
---|
authentication3DSecure. md | string | Conditional |
Unique identifier. In 3DS V2, it is the threeDSServerTransID.
Must be sent for first payment.
Either (md, pares ) or resultContainer must be present. Commonly: - if frictionless, the resultContainer is used,
- if challenge, md and pares are used
If the merchant didn't provide the md the verifyEnrollment response returned the value determined by Payline. |
Can be empty for subsequent payment |
authentication3DSecure. pares | string | Conditional | Either (md, pares ) or resultContainer must be present. Commonly: - if frictionless, the resultContainer is used,
- if challenge, md and pares are used
In case of challenge in 3DS V2, the pares field shall be valued with the content of the CRes received from the ACS |
authentication3DSecure.resultContainer
| string | Conditional |
In case of frictionless, this field is constructed from 3DS V2 data by Payline. It contains all data required by Payline to format and process the Authorization. This field is base64 encoded. | payment.action
string | Mandatory | This field is used to describe the use case. Without 3DS V2 the merchant was using only 3 values : - 109 for 0€ authorization without CVV
- 108 for 0€ authorization with CVV
- 120 for authorization without CVV
New values will be created in order to manage new use cases : - Single Charge : 120
- Recurring Payment with no fixed date nor amount :
- First authorization (0€) and CVX present : 108
- First authorization (0€) and CVX absent : 109
- First authorization with an amount present and not 0 and CVX absent : 128
- Subsequent authorization : 128
- Split shipment : 126
| Either (md, pares ) or resultContainer must be present. Commonly: - if frictionless, the resultContainer is used,
- if challenge, md and pares are used
In case of frictionless, this field is constructed from 3DS V2 data by Payline. It contains all data required by Payline to format and process the Authorization. This field is base64 encoded. |
| string | Mandatory | This value depends on the payment case the merchant issues |
linkedTransactionID
string | Conditional | This field is used to send the initial transaction ID created by the issuer to link authorizations to one Authentication | payment.cumulatedAmount
number | Conditional | This field is used to send the amount already successfully authorized in case of split shipment.
In the lowest unit of the currencyOther fields has not been modified and should be used as previously.
In the response, two very important fields are added :
Payline Field Name | Format | Mandatory | Comment |
---|
linkedTransactionID | string | Conditional | Issuer transaction ID to be used on subsequent Authorization |
authentication3DSecure.resultContainer | string | Mandatory | In case of frictionless, the field is echoing the request field In case of challenge, this field is constructed from 3DS V2 data by Payline. It contains all data required by Payline to format and process the subsequent Authorization. |
Other fields has not been modified and should be used as previously.
The message snippet below describes the parameters to be added:
Bloc de code |
---|
language | xml |
---|
theme | Confluence |
---|
title | doAuthorizationRequest message snippet : how to valuate the authentication3DSecure object |
---|
|
collapse | true |
---|
...
<transientData>{JSON}</transientData> <!-- from previous verifYEnrollement call -->
...
<authentication3DSecure>
<md>2F04CC56F968373D0114AD4B6BB4E4F1</md>
<!-- In case of challenge, the pares field shall be valued with the content of the CRes received from the ACS -->
<!-- In case of 3DS V1, this field shall be valued with the content of the PaRes received from the ACS -->
<!-- In other cases, this field is left empty -->
<pares>eJxVUl1vgjAU/SvG99EPaAVzbeJwycyCOpQl28vC...GUY8y9ux4x1+U2M9F3PcY9MxES7HX2BgAyLqh/VdQ/vK7+fYhfHAOuMA==</pares>
<!-- In case of frictionless, the resultContainerfield shall be valued with the content of the resultContainer -->
<!-- present in the verifyEnrollmentResponse-->
<!-- In other cases, this field is left empty -->
<resultContainer>eyAidGhyZWVEU1NlcnZlclRyYW5z....QVTc4MUpiOVZnbHhVZnA1Z0Q4JTNEIiB9</resultContainer>
</authentication3DSecure>
... |
New response code
Payline will respond with some new codes related to 3DSV2
Code | Comment |
---|
01131 | Authorization refused, SCA required. Should happened only on "direct to auth" |
01132 | Recurring payments on the currently used MID are revoked, SCA required. |
01133 | Recurring payments on all MID are revoked, SCA required. |
title | showLabels | false |
---|
showSpace | false |
---|
sort | title |
---|
|
Linked pages | cql | label = "3dsv2" and label = "en" |
---|
|