Introduction

What is 3DSecure ?

The 3DSecure process adds a security layer to an online purchase: the buyer will usually validate his payment by entering a one-time passcode provided by their bank via text messsage. Other methods also exist. When a transaction is authenticated with 3DSecure, the liability in case of a subsequent chargeback is borne by the issuing bank. This is refered to as the principle of liability shift.

Payline holds Visa and Masterdard International (MCI) 3DSecure certifications.

Subscription

The merchant gets a 3DSecure Distance Selling contract with their bank and sends the details to Payline.
Payline registers the 3DSecure contrat with Visa and MCI then activates the contracts. Allow up to ten working days for activation.

Prerequisites for using Payline payment solution

The 3DSecure solution in Direct interface mode ensures the secure transfer of sensitive data and processes authentication and authorization requests.

Integration points :

• verifyEnrollment is required to provide authentication and doAuthorization to perform the authorization;
• get the result of the transaction with getTransactionDetails.

You must check the service access key and configure the SOAP UI.

3D-Secure in Direct Interface mode with a payment

The following steps present verifyEnrollment and doAuthorization web services for realizing  3DSecure transactions using the Direct interface.

Step 1 - verifyEnrollment 

This first call is to verify the eligibility of the card to a 3DSecure authentication, and therefore to know if the cardholder is registered with a VISA or Mastercard Directory Server. This is done with the verifyEnrollment web service.

Example of a request and response for the verifyEnrollment web service :

Introduction

Pré-requis bancaire et de connexion 3DSecure

Ce traitement repose sur la mise en place d'un contrôle supplémentaire lors d'un achat en ligne : en complément des données bancaires, l'acheteur validera son paiement en saisissant une donnée secrète que lui aura fourni sa banque.
Ce dispositif s'accompagne d'une évolution réglementaire appelée "liability shift" ou "transfert de responsabilité" dont le principe est de faire supporter le risque d'impayé émis pour contestation du porteur à la banque du porteur et non plus au commerçant, si le porteur a validé son paiement en renseignant les données 3D Secure et que le commerçant a respecté les mesures de sécurité énoncées dans les conditions générales de vente de son contrat de commerce électronique souscrit auprès de sa banque.

La solution de paiement Payline a déroulé une certification 3DSecure avec les banques, ainsi qu'avec Visa et MCI.

Souscription 

Le commerçant doit souscrire auprès de sa banque à un contrat VADS (VAD type 3D Secure).
Le commerçant informe Payline qu'il a souscrit à un contrat VADS avec 3DSecure, et le client souhaite souscrire à l'option 3DSecure.
L'équipe Payline, doit procéder à l'enregistrement du commerçant auprès de Visa et MCI, « un délai de 10 jours est nécessaire »
Dès confirmation des réseaux Visa et MCI, l'équipe Payline informe le commerçant qu'il va procéder à l'activation du contrat VADS.
Dès activation du contrat VADS, tous les flux transitant sur ce contrat seront des transactions 3DS.

Pré-requis d'utilisation de la solution de paiement Payline

La solution 3D Secure en mode interface Direct assure le transfert sécurisé des données sensibles et traite les demandes d'authentification, d'autorisation.

Les points d'intégration :

• verifyEnrollment est nécessaire pour assurer l'authentification et doAuthorization pour réaliser l'autorisation ;
• récupérer le résultat de la transaction avec gettransactionDetails.

Vous devez vérifier la clé d'accès des services et configuration le paramétrage SOAP UI.

3D-Secure en mode interface direct avec un paiement

Cette page présente les deux web services « verifyEnrollment et doAuthorization » permettant d'effectuer une transaction 3DSecure en utilisant le mode interface direct de la solution de paiement Payline.

Etape 1 : verifyEnrollment

Ce premier appel web service permet de vérifier l'éligibilité du porteur au dispositif 3DSecure, et donc de savoir si le porteur de la carte est bien enregistré auprès d'un Directory Server VISA ou Mastercard.

Once enrolment has been confirmed, an authentication call to the ACS server can be initiated. Information received from the verifyEnrollmentResponse must be sent to the authentication server.

Sending information

To send this information :

• in POST : create an HTML form,
• in GET : create a link.

POST : The data information will be sent to the authentication server via the form below.
The field names and values ​​are dynamically retrieved from the verifyEnrollmentResponse : 

• Payment session: 

Envoi des informations

Pour envoyer ces informations, il suffit de créer un formulaire HTML en si POST ou de constuire un lien si GET :

POST : Les informations seront envoyées au serveur d'authentification à travers le formulaire ci-dessous. Les noms des champs et des valeurs sont récupérés dynamiquement du verifyEnrollmentResponse.

• suivi de la session : valeur à récupérer dans la réponse du verifyEnrollment

  • mdFieldName = MD

  • mdFieldValue = 1Fz9nEnAZJNn8NvXEKDT

• requête d'authentification :  valeur à récupérer dans le verifyEnrollment

  Authentication request: 

  • pareqFieldName = PaReq

  • pareqFieldValue  = eJxVkdtuwjAMhl+l4gGaA...

  Adresse où le serveur d'authentification. Cette adresse doit être capable de récupérer un formulaire envoyé en « POST » et contenant la réponse de l'authentification de l'utilisateur

• Authentication adress server. This address must retrieve a form sent in POST.

  • termUrlName = TermUrl
    termUrlValue  =  https://acs.modirum.com/mdpayacs.php 

Exemple de formulaire HTML pour réaliser un test sur votre serveur :

Sample HTML form to perform a test on your server:

Réception des informations retournées lors de l'authentification

Le serveur d'authentification envoi son message sur l'URL renseignée dans le paramètre TermURL (envoyé dans le formulaire précédent). Dans le formulaire de réponse, deux champs doivent être récupérés pour poursuivre la transaction en mode 3DSecure :

• Le champ MD : toujours le même champ permettant le suivi de la session

• le champ PaRes (Payer Authentication Response) : chaine de caractères cryptée contenant la réponse du serveur d'authentification. La valeur du champ PaRes va permettre de valider ou non la transaction comme une transaction 3DSecure.

Receipt of information returned during authentication

The authentication server sends its message to the URL entered in the TermURL parameter (sent in the previous form). In the response form, two fields must be retrieved to continue the transaction in 3DSecure mode:

• The MD field: always the same field allowing the follow-up of the session

• the Payer Authentication Response (PaRes) field: an encrypted string containing the response of the authentication server. The value of the PaRes field will validate or not the transaction as a 3DSecure transaction.

These two fields are retrieved and allow to complete the doAuthorizationRequest in 3DSecure mode.

Sample script (here written in PHP) to retrieve the response to authentication 

:

Remarque Note: ce script doit être placé sur un serveur web démarré et dans un dossier correspondant à l'adresse envoyé via le champ TermURL. This script must be placed on a started web server and in a folder corresponding to the address sent via the TermURL field.

Example: if the server is local it is quite possible to put as value Exemple : si le serveur est en local il est tout à fait possible de mettre comme valeur :

TermURL = http://127.0.0.1/3DSecure/receive_form.php

Step 2 : doAuthorizathion

with3D Secure

settings

The doAuthorization service allows you to perform the transaction with the 3DSecure parameters.
The parameters provided : md / pares permit to check user authentication and thus the user identity before carrying out the transaction.

If the parameters are correct, the transaction is carried out as authorization request

.

3D-Secure en mode interface direct avec la possibilité ou pas d'effectuer un paiement

Il est possible d'utiliser la fonction 3DSecure implémentée sur la solution de paiement Payline, sans utiliser la fonction standard de Payline « effectuer un paiement », donc vous utiliserez uniquement les deux premières étapes décrites ci-dessous.
En effet l'Etape 3, permet d'effectuer une transaction de paiement en vous appuyant de la solution de paiement 3DSecure.

Étape 1 : appel du web service verifyEnrollment

Comme expliqué précédemment, cette première action permet de vérifier l'enrôlement de la carte de l'utilisateur. Les éléments obligatoires de la méthode verifyEnrollment sont :

• card : numéro de carte / type / date d'expiration / cvx
• payment : montant / devise / action / mode / numéro contrat
• orderRef

• amount = 1000
• currency = 978
• action = 101
• mode = CPT
• orderRef = RefTest01

• number = 4970100000000238
• type = CB
• expirationDate = 0610
• CVx : 123

verifyEnrollmentRequest

verifyEnrollmentResponse

<impl:verifyEnrollmentRequest>
<impl:card>
<obj:number>4970100000325734</obj:number>
<obj:type>CB</obj:type>
<obj:expirationDate>0610</obj:expirationDate>
<obj:cvx>123</obj:cvx>
</impl:card>
<impl:payment>
<obj:amount>1000</obj:amount>
<obj:currency>978</obj:currency>
<obj:action>100</obj:action>
<obj:mode>CPT</obj:mode>
<obj:contractNumber>CB3DS</obj:contractNumber>
</impl:payment>
<impl:orderRef>RefTest01</impl:orderRef>
</impl:verifyEnrollmentRequest>

<verifyEnrollmentResponse>
<result>
<code>03000</code>
<shortMessage>ACCEPTED</shortMessage>
<longMessage>Operation Successfull</longMessage>
</result> <actionUrl>

</actionUrl>
<actionMethod>POST</actionMethod>
<pareqFieldName>PaReq</pareqFieldName>
<pareqFieldValue>
eJxVkdtygjAQhl/F8QHcJAUBZ90Zj4MXbdHaXvSOC
TuVTkEM0OrU9ir7bfb4L253hnn+wro1TPjIdZ1+cC/Pxn3
lh0J4fcJksuED4TebOt+XJAdioBCuaHOM3qVlQ5jq
QCnnQ/fz1olTNc6hNFQWhnvxLysdqXbCOsWDcbM661X
aN77jvMYqefbqw4SoSRcrU6dpVyK4e0o59LOUBwG
dDdBrrDWevfQX8B2heclQ==
</pareqFieldValue>
<termUrlName>TermUrl</termUrlName>
<termUrlValue>

</termUrlValue>
<mdFieldName>MD</mdFieldName>
<mdFieldValue>8FPL0ihqQtuqr1GzmOCL</mdFieldValue>
</verifyEnrollmentResponse>

• 02101 - Internal Error - Internal Error
• 02303 – Invalid Transaction – Invalid Contract Number
• 02305 – Invalid Transaction - Invalid field format
• 03000 - Operation Successfull – Operation Successfull
• 03001- Operation Refused – Not Enrolled
• 03002 - Operation Refused - Not participating
• 03021 – Transaction Refused - Enrollment verification failed
• 09201 - Access Refused - You do not have permissions to make this API call

• PAReq : Payer Authentication Request : suite de caractères regroupant la requête à envoyer au serveur d'authentification, permet d'identifier la carte et son le titulaire.
• MD : Merchant Date : identifiant permettant d'identifier le commerçant et de simuler une session entre les requêtes d'enrôlement et d'authentification sur les serveurs Access Control Server (ACS) et Merchant Plug-in (ou MPI).
• actionURL : URL indiquant où doivent être envoyées les informations permettant de vérifier l'authentification de l'utilisateur (voir ci-dessous).
• actionMethod : méthode devant être utilisée pour envoyée les informations au serveur d'authentification (voir ci-dessous).

Étape 2 : authentification

Une fois le verifyEnrollment effectué, l'authentification auprès du serveur ACS doit être effectuée. Pour cela, il est nécessaire d'envoyer les informations du verifyEnrollment sur le serveur d'authentification. Les informations attendues par le MPI sont le MD (pour le suivi de session) et le paReq (requête d'authentification).

Envoi des informations

Pour envoyer ces informations, il suffit de créer un formulaire HTML regroupant les champs MD et paReq et pointant vers le serveur d'authentification.

Formulaire HTML

<form name="downloadForm" action="https://acs.modirum.com/mdpayacs/pareq" method="POST">
<input type="hidden" name="TermUrl" value="http://127.0.0.1/3DSecure/receive_form.php">
PAREQ : <input type="text" name="PaReq">
<br />
MD : <input type="text" name="MD">
<br />
<input type="submit" name="submit" value="Submit">
</form>

• MD : suivi de la session : valeur à récupérer dans la réponse du verifyEnrollment
• PaReq : requête d'authentification : valeur à récupérer dans le verifyEnrollment
• TermURL : adresse où le serveur d'authentification envoie la réponse de l'authentification. Concrètement cette adresse doit être capable de récupérer un formulaire envoyé en « POST » et contenant la réponse de l'authentification de l'utilisateur.

Attention ces valeurs sont générés de manière dynamique et se renouvelleront à chaque demande.

Réception des informations retournées lors de l'authentification

Script PHP : receive_form.php

Étape 3 : doAutorization

La dernière étape dans le cadre d'une transaction 3DSecure via l'interface Payline DIRECT est l'envoi d'une requête doAuthorization. Comme dans le cadre d'une transaction classique, le doAuthorization contiendra les champs obligatoires suivant :

• payment : informations sur la transaction : montant, devise, contrat, etc.
• card : informations sur la carte de paiement : numéro, type, date d'expiration, etc.
• order : information sur la commande : référence, montant, pays, etc.
  Et donc dans le cadre d'un paiement 3DSecure, la requête doAuthorization devra être complétée avec les informations renvoyées par le serveur d'authentification :
• MD : suivi de session 3DSecure.

• PaRes : résultat de l'authentification.

doAuthorizationRequest

doAuthorizationResponse

Back Office

Menu 'Technical follow-up of webservice calls' to find the call of the web service verifyEnrollment allows to see the details of the verifyEnrollment.

The result of the 3DSecure transaction is then visible in the Payline Administration Center: on the results of a search and in the detail of the transaction 3DSecure tab.

Screen searches for transactions:

Image Added

3DSecure transaction Details:

Image Added

3D Secure payment scheme

1. The consumer validates his cart shopping then the merchant prepares web page to where will be filled the payment data.
   A VEReq (Verification Enrollment Request) message allows access to Directory Server to verify cart registration in the directory containing cards declared "enlisted" 3-D Secure and provide ACS URL.
   Verification enrollment response containing authentication result, that will be returned to Merchand Plug-in (MPI) to manage the dialogue with Directory and ACS to allow the buyer to authenticate.
2. The merchant redirects the consumer to ACS URL for authentication.
   The request "PAReq" (Payer authentication request) allows access to bank ACS to trigger the authentication phase.
   The response "PARes" (Pay authentication response), containing the authentication result of cardholder will be transmitted to the merchant.
3. The merchant can trigger a request for authorization and payment validation by calling service doAuthorizationRequest.
4. The merchant retrieves details transaction by calling service getTransactionDetails.

<doAuthorizationResponse>
<result>
<code>00000</code>
<shortMessage>ACCEPTED</shortMessage>
<longMessage>Transaction approved</longMessage>
</result>
<transaction>
<id>90224141650893</id>
<date>24/02/09 14:16</date>
<isDuplicated>0</isDuplicated>
<isPossibleFraud>0</isPossibleFraud>
<fraudResult/>
<explanation/>
<threeDSecure>Y</threeDSecure>
<score xsi:nil="true" />
</transaction>
<authorization>
<number>A55A</number>
<date>24/02/09 14:16</date>
</authorization>
</doAuthorizationResponse>

Centre administration

Menu 'Suivi technique des appels webservice' pour retrouver l'appel du web service verifyEnrollment permet de voir le détail du verifyEnrollment.

Le résultat de la transaction 3DSecure est alors visible dans le centre d'administration Payline : sur les résultats d'une recherche et dans le détail de la transaction onglet 3DSecure :

Ecran recherche des transactions :

Image Removed

Image Removed

Image Removed

Schéma du paiement 3D Secure

Image Removed