French | English |
Content
These pages describe how the merchants request Payline for an authorization coupled with a 3DS V2 authentication.
Exchanges outlines
The exchanges consist in 3 steps:
- Verify enrollment which tells the merchant how authenticate the buyer for the requested order
- Challenge (optional), which represents the connection of the buyer to 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 theverifyEnrollment
ordoAuthorization
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
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
The merchant sets up the html form according to the response parameters of the verifyEnrollment
web service as follows
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
orCRes
contains the Payment Authentication Response that must be sent in to thedoAuthorization
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
The cardBrand (ie. scheme) in the doAuthorizaton
must be the same as in the authentication
JSON Container
The JSON container format is described here : 3DS V2 JSON container format
Authentication 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.
The returnCode present in the verifyEnrollmentResponse
message tells the merchant how to continue:
03101
: The ACS requires a challenge to authenticate the buyer description03102
: The ACS authenticated the buyer in frictionless mode description03000
: The buyer shall authenticated using 3DS V1 description03100
: The ACS requires the 3DS Method to be called description
Authentication with challenge
The merchant receives the following 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 :
When the buyer is done with the authentication, the merchant retrieves the CRes
message base64 encoded posted by the ACS to the termURL
.
Frictionless authentication
The merchant receives the following verifyEnrollmentResponse
3DS V1 fallback
The merchant receives the following 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 handling
Return 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 | 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' |
The ACS requires the 3DS Method to be called
The ACS may require that before anything the buyer's browser to be redirected to it.
In that case, Payline renders a returnCode
set to 03100
.
The merchant receives the following 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 :
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 the threeDSInfo
.threeDSMethodResult
parameter set to 'Y
'
Otherwise he adds 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 AuthorizationPayline Field Name | Format | Mandatory | Comment |
---|---|---|---|
authentication3DSecure. md | string | Conditional | Unique identifier. In 3DS V2, it is the threeDSServerTransID. Must be sent for first payment. Can be empty for subsequent payment |
authentication3DSecure. pares | string | Conditional | In case of challenge, the pares field shall be valued with the content of the CRes received from the ACS |
| 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. |
| string | Mandatory | This field is used to describe the use case. Without 3DS V2 the merchant was using only 3 values :
New values will be created in order to manage new use cases :
|
| string | Conditional | This field is used to send the initial transaction ID created by the issuer to link authorizations to one Authentication |
| number | Conditional | This field is used to send the amount already successfully authorized in case of split shipment. In the lowest unit of the currency. |
Other 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:
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. |