Transaction initiée par le porteur (CIT – BRW)

Temps estimé :11 minutes

Le flux BRW (Browser) s’applique aux transactions initiées par le client (CIT — Customer-Initiated Transaction) : le titulaire de la carte est présent et valide lui-même le paiement. Cette CIT authentifiée sert aussi de socle aux transactions MIT futures.

👉 Pour une transaction initiée par le marchand sans le porteur (facturation récurrente, montant variable, usage-based, frais ponctuels), consultez la documentation du flux 3RI.

❌ Attention au choix du flux : utiliser le BRW pour une transaction initiée par le marchand (MIT) entraîne une non-conformité, une friction inutile et une réduction importante du taux de conversion.

1. Les grandes étapes du flux BRW

Le flux BRW enchaîne cinq étapes côté API, dont deux conditionnelles : versioning (la carte est-elle authentifiable ?) → 3DS Method (si nécessaire) → authentification → challenge (si la banque l’exige) → résultat, avant de réaliser la transaction.

Schéma du flux 3DS 2.2 BRW
ℹ️ Tout le processus doit se dérouler sur une seule et même page web, sans redirection vers une page bancaire, grâce à une solution d'iframe. C'est une contrainte du process bancaire.

Pour accélérer votre intégration du flux BRW, vous pouvez partir d’une application d’exemple complète (PHP / Twig) qui rejoue toute la séquence décrite sur cette page : formulaire de paiement CUSTOM, versioning, 3DS Method en iframe, authentication, gestion du challenge, results puis transaction, le tout sur une seule et même page, conformément à la contrainte bancaire.

👉 Télécharger le code d’exemple  ·  Voir la démo en ligne

Avant de lancer le code d'exemple, renseignez vos identifiants dans le fichier .env (API_USER, API_PASSWORD, POS_UUID) et faites pointer HOST_CENTRALPAY_API_CORE vers l'environnement de test https://test-api.centralpay.net/v2/rest/.

2. Versioning

Le versioning est la première étape : il interroge le réseau de la carte pour savoir si elle peut être authentifiée en 3DS 2.2, et récupère les éléments techniques nécessaires à la suite. Concrètement, vous adressez à l’API CentralPay le PAN de la carte (Primary Account Number, le numéro à 16 chiffres).

Exemple (curl) :

curl --location --request POST 'https://test-api.centralpay.net/v2/rest/3ds2/versioning' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--data-urlencode 'acctNumber=4000001000000067'

Comprendre la réponse. Une carte est dite « enrôlée » lorsque la banque qui l’a émise participe au protocole 3DS 2.2 pour cette carte. C’est la banque émettrice qui en décide : ni vous ni CentralPay ne pouvez enrôler une carte. Le versioning sert justement à savoir si c’est le cas.

  • Carte non enrôlée → le versioning retourne une erreur 404 : l’authentification 3DS 2.2 est impossible pour cette carte. Prévoyez un repli (basculement en 3DS1 si supporté, ou refus du paiement selon votre politique de risque).
  • Carte enrôlée → vous recevez un identifiant d’opération, le threeDSServerTransID (généré par CentralPay et conservé jusqu’au résultat final), ainsi que, le cas échéant, les données nécessaires au « 3DS Method » (une URL + une donnée encodée en base64).

Pour une carte enrôlée, deux réponses sont possibles :

Version 1 (la plus fréquente) — un 3DS Method est attendu :

{
    "threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
    "threeDSMethodURL": "https://test-3dss-demo.centralpay.net/acs/3ds-method",
    "threeDSMethodDataForm": {
        "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0LTNkc3MuY2VudHJhbHBheS5uZXQvM2RzLzNkcy1tZXRob2Qtbm90aWZpY2F0aW9uLyIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOWNjNmIzM2MtZGQzNS00ZmJkLTgxY2QtZmQ5Y2YwYWVlZDljIn0="
    },
    "errorDetails": null
}

Les champs threeDSMethodURL et threeDSMethodData sont renseignés : passez à l’étape 3. 3DS Method.

Version 2 — pas de 3DS Method :

{
    "threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
    "threeDSMethodURL": null,
    "threeDSMethodDataForm": null,
    "errorDetails": null
}

Seul threeDSServerTransID est renseigné (les champs 3DS Method sont vides) : passez directement à l’étape 4. Authentification.

3. 3DS Method

À quoi ça sert ? Le 3DS Method permet à la banque du porteur — via son ACS (Access Control Server, le serveur de la banque émettrice qui authentifie le porteur) — de collecter discrètement des informations techniques sur le navigateur du client, avant l’authentification. Ces informations enrichissent son analyse de risque et augmentent les chances d’une authentification frictionless (sans challenge pour le porteur).

Quand l’exécuter ? Uniquement si le versioning a renvoyé une valeur pour threeDSMethodURL et threeDSMethodData (cas « Version 1 » ci-dessus). Sinon, passez directement à l’authentification.

Comment ? Chargez l’threeDSMethodURL dans une iframe invisible (masquée à l’écran : cet échange est purement technique et ne doit rien afficher au porteur) et postez-y le champ threeDSMethodData. C’est le navigateur du porteur qui effectue cet appel vers la banque, en arrière-plan.

4. Authentification (BRW)

L’appel est adressé à l’URL 3ds2/authentication de l’API CentralPay. Cette requête transmet les données contextuelles liées au porteur et à son navigateur, qui permettent à la banque de décider si une authentification active (challenge) est nécessaire.

Exemple (curl) :

curl --location --request POST 'https://test-api.centralpay.net/v2/rest/3ds2/authentication' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--data-urlencode 'threeDSServerTransID=7d031b8e-7fb7-4215-b866-eaacb395002f' \
--data-urlencode 'cardTokenId=5b9nb5cf-4470-4e58-b690-dd8965860eb8' \
--data-urlencode 'deviceChannel=02' \
--data-urlencode 'messageCategory=01' \
--data-urlencode 'purchaseAmount=1000' \
--data-urlencode 'purchaseCurrency=EUR' \
--data-urlencode 'threeDSRequestorAuthenticationInd=01' \
--data-urlencode 'browserJavaEnabled=true' \
--data-urlencode 'browserLanguage=fr-FR' \
--data-urlencode 'browserColorDepth=24' \
--data-urlencode 'browserScreenHeight=1052' \
--data-urlencode 'browserScreenWidth=1853' \
--data-urlencode 'browserTZ=120' \
--data-urlencode 'browserIP=127.0.0.1' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:68.0) Gecko/20100101 Firefox/68.0' \
--data-urlencode 'browserAcceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
--data-urlencode 'notificationURL=http://dev4.dev.centralpay.net:1101/requestor/challenge-notification' \
--data-urlencode 'threeDSRequestorURL=https://www.centralpay.eu'

💡 deviceChannel=02 indique le canal navigateur, propre au flux BRW. Les paramètres browser* (caractéristiques du navigateur du porteur) sont donc obligatoires ici.
Pour augmenter le taux d'authentification Frictionless, enrichissez cette requête avec les données contextuelles du porteur → voir Optimiser le taux de Frictionless

Champs à préciser selon l’objet de la CIT. Le champ threeDSRequestorAuthenticationInd est obligatoire : il indique la nature de l’authentification. Une CIT BRW peut servir soit à authentifier un paiement (messageCategory=01, PA), soit à authentifier une carte ou son porteur sans débit (messageCategory=02, NPA) — par exemple pour enregistrer une carte, la mettre à jour ou en vérifier le porteur. Les deux champs se renseignent de façon cohérente :

threeDSRequestorAuthenticationIndObjet de la CITmessageCategoryChamps requis en plus
01 — PaymentPaiement unitaire (ponctuel)01 (PA)—
02 — RecurringPaiement récurrent (abonnement)01 (PA)recurringExpiry, recurringFrequency
03 — InstalmentPaiement échelonné (en plusieurs fois)01 (PA)recurringExpiry, recurringFrequency, purchaseInstalData
04 — Add cardEnregistrement / empreinte d’une carte pour usage futur, sans débit02 (NPA)—
05 — Maintain cardMise à jour des informations d’une carte déjà enregistrée (ex. renouvellement)02 (NPA)—
06 — Cardholder verificationVérification du porteur dans le cadre de l’ID&V d’un token EMV02 (NPA)—
  • recurringExpiry → date après laquelle plus aucune autorisation ne sera effectuée (format YYYYMMDD).
  • recurringFrequency → nombre minimum de jours entre deux autorisations (1 à 999).
  • purchaseInstalData → nombre maximum d’autorisations (échéances) prévues pour le paiement échelonné (1 à 999).
ℹ️ Les cas 04, 05 et 06 sont des authentifications hors paiement : aucun montant ni champ de récurrence n'est requis. Elles ne préparent pas forcément une MIT — ce sont souvent une fin en soi (enregistrer, vérifier ou maintenir une carte). La carte ainsi authentifiée pourra ensuite servir à des transactions CIT (porteur présent) comme MIT (3RI).

La réponse contient un statut d’authentification (transStatus) qui détermine la suite à donner :

❌ Pas d’autorisation — ne pas effectuer la transaction

Statut (transStatus)Signification
NNon authentifié / compte non vérifié. Transaction refusée.
UAuthentification / vérification impossible (problème technique ou autre).
RAuthentification / vérification rejetée. L’émetteur demande de ne pas tenter d’autorisation.
IInformation seulement. Reconnaissance de la préférence du demandeur pour le challenge 3DS.

✅ Autorisation sans challenge

Statut (transStatus)Signification
YAuthentification réussie.
ATentative effectuée. Non authentifié / vérifié, mais une preuve de tentative est fournie.

🔐 Autorisation après challenge

Statut (transStatus)Signification
CChallenge requis : le porteur doit s’authentifier activement (voir étape 5), via les messages CReq/CRes (Challenge Request / Response).
DChallenge requis. Authentification découplée confirmée.

Exemples de réponses :

C — Challenge requis :

{
    "threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
    "transStatus": "C",
    "acsTransID": "375d90ad-3873-498b-9133-380cbbc8d99d",
    "acsURL": "https://test-3dss-demo.centralpay.net/acs/challenge",
    "acsChallengeMandated": "Y",
    "base64EncodedChallengeRequest": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU2MDFlYjQ0LTU2N2MtNDM4Ny05MmZjLWU2ZjIzMjJiODIyYiIsImFjc1RyYW5zSUQiOiI3ZTQzZDI4ZC00M2RkLTRmM2MtYTcwOS00YjZkZDVlZjc5Y2QiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
    "contractId": "71602dd0-2790-4743-877b-e72530d7576d"
}

Y — Authentification réussie (challenge non nécessaire) :

{
    "threeDSServerTransID": "7d994177-32d8-43f7-87a4-3a3cd734cbfe",
    "transStatus": "Y",
    "acsTransID": "375d90ad-3873-498b-9133-380cbbc8d99d",
    "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjEa",
    "eci": "02",
    "contractId": "71602dd0-2790-4743-877b-e72530d7576d"
}

Les champs requis pour la transaction sont présents : threeDSServerTransID, transStatus, authenticationValue (le cavv — Cardholder Authentication Verification Value, le cryptogramme qui prouve l’authentification) et eci (Electronic Commerce Indicator, qui indique le niveau d’authentification obtenu et conditionne le transfert de responsabilité en cas de fraude). Le xid n’est pas fourni : c’est une référence libre destinée aux marchands.

N — Transaction refusée :

{
    "threeDSServerTransID": "6396b832-3e5b-4143-bde6-f5r1c1e47da0",
    "transStatus": "N",
    "eci": "00",
    "contractId": "258128f3-5db9-4235-918a-f1d786f67c29"
}

5. Challenge

Le challenge est l’étape où le porteur s’authentifie activement auprès de sa banque (code à usage unique reçu par SMS, validation dans l’application bancaire, biométrie…). Il n’a lieu que si l’authentification a renvoyé transStatus = C.

  • Une iframe doit soumettre un formulaire à l’acsURL retournée à l’étape 4.
  • Le seul paramètre envoyé est creq, dont la valeur est le base64EncodedChallengeRequest issu de l’authentification.
  • À la fin du challenge, l’URL que vous avez fournie (notificationURL) est appelée par la banque.

En environnement de test, le challenge s’affiche sous forme d’un OTP (One-Time Password, code à usage unique) ; en production, c’est la fenêtre de l’ACS de la banque qui s’affiche :

Fenêtre de challenge OTP en environnement de test

OTP de test :

  • 1234 → Y (simule un challenge réussi – Authentification réussie)
  • 4444 → A (simule un challenge réussi – Non authentifié / vérifié, mais une preuve de tentative est fournie.)
  • 1111 → N (simule un challenge échoué – Non authentifié / compte non vérifié)
  • 2222 → R (simule un challenge échoué – Authentification / vérification rejetée)
  • 3333 → U (simule un challenge échoué – Authentification / vérification impossible (problème technique ou autre)

6. Réponse du challenge

À l’issue du challenge, le résultat est transmis dans le paramètre cres, encodé en base64. Décodez-le pour lire le statut. Exemple en PHP :

$retour = json_decode(base64_decode($_POST['cres']), true);
  • Si le statut est Y ou A, le challenge est validé et le paiement est autorisé : appelez GET /results (étape 7) pour récupérer les données 3DS nécessaires à la transaction.
  • Toute autre valeur signifie que le challenge a échoué : le paiement est refusé.

7. Résultat

Cette étape récupère les données 3DS définitives à reporter dans la transaction. Adressez le threeDSServerTransID de l’authentification.

ℹ️ Si l'authentification a directement retourné transStatus = Y (sans challenge), les données 3DS y figurent déjà : cette étape n'est pas nécessaire.

Appel :

curl --location -g --request GET 'https://test-api.centralpay.net/v2/rest/3ds2/results/{{threeDSServerTransID}}' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA=='

Réponse :

{
    "threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
    "transStatus": "Y",
    "acsTransID": "375d90ad-3873-498b-9133-380cbbc8d99d",
    "authenticationValue": "JAmi21makAifmwqo2120cjq1AAA=",
    "eci": "01"
}

🔁 Préparer les MIT futures (3RI). Si cette CIT doit servir de référence à des paiements ultérieurs initiés par le marchand, conservez l'acsTransID de la séquence d'authentification : il sera requis comme threeDSReqPriorRef côté 3RI.

8. Transaction

Données à renseigner pour valider une transaction authentifiée en 3DS 2.2 :

  • 3ds[threeDSServerTransID] = threeDSServerTransID
  • 3ds[status] = transStatus
  • 3ds[cavv] = authenticationValue
  • 3ds[eci] = eci (obligatoire si disponible)
  • 3ds[xid] = paramètre custom, référence libre destinée aux marchands

Exemple (curl) :

curl --location --request POST 'https://test-api.centralpay.net/v2/rest/transaction' \
--header 'Origin: https://example.centralpay.net' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'currency=EUR' \
--data-urlencode 'amount=1500' \
--data-urlencode 'endUserIp=9.64.32.8' \
--data-urlencode 'endUserLanguage=ita' \
--data-urlencode 'merchantTransactionId=cpcg_12654de89ce44' \
--data-urlencode 'pointOfSaleId=1beb8574-cf4c-4b12-b065-d12b3f0eaa90' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (iPhone; CPU iPhone OS 16_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Mobile/15E148 Safari/604.1' \
--data-urlencode 'browserAcceptLanguage=it_IT' \
--data-urlencode 'paymentRequestBreakdownId=5485d7e6-60c3-753c-94d3-682eaaf9ae6e' \
--data-urlencode 'email=support@centralpay.eu' \
--data-urlencode 'receiptEmail=support@centralpay.eu' \
--data-urlencode 'capture=true' \
--data-urlencode 'cardTokenId=5b9nb5cf-4470-4e58-b690-dd8965860eb8' \
--data-urlencode 'order[cardholderEmail]=support@centralpay.eu' \
--data-urlencode 'order[firstName]=John' \
--data-urlencode 'order[lastName]=Doe' \
--data-urlencode 'source=EC' \
--data-urlencode '3ds[xid]=35876533346561303461' \
--data-urlencode '3ds[cavv]=JAmi21makAifmwqo2120cjq1AAA=' \
--data-urlencode '3ds[eci]=01' \
--data-urlencode '3ds[status]=Y' \
--data-urlencode '3ds[threeDSServerTransID]=7d031b8e-7fb7-4215-b866-eaacb395002f'

Étape suivante : pour les transactions ultérieures initiées par le marchand (MIT), voir 3DS 2.2 – 3RI.

Transaction initiée par le porteur (CIT – BRW) - PreviousAuthentification 3DS 2.2Next - Transaction initiée par le porteur (CIT – BRW)Transaction initiée par le marchand (MIT – 3RI)
CONTENU