WL SIPS DOCS

Release 25.4

aller directement au contenu

Rechercher par mots clés

On behalf merchant token

Pour rechercher dans la page utiliser Ctrl+F sur votre clavier

L'objectif du présent document est de présenter l'intégration de l'utilisation des scheme tokens dans le process de paiement avec merchant token.

Ce document s’adresse aux commerçants et à leurs équipes techniques qui souhaitent exploiter les scheme tokens dans leurs transactions CIT (Customer Initiated Transaction) ou MIT (Merchant Initiated Transaction) dans un contexte Card-on-file (COF) avec un merchant token.

Pour avoir une vue d’ensemble de la solution Worldline Sips, nous vous conseillons de consulter les documents suivants :

Ce schéma décrit les relations techniques entre le marchand, Worldline Sips et les différents TSPs (Token Service Provider).


schéma qui décrit les relations entre le marchand, Worldline et les différents TSP

Worldline Sips communique avec les TSPs pour le compte du commerçant, qui n'échange pas directement avec les TSPs.

L'inscription auprès des TSP passe par Worldline Sips. Toutefois, il est préférable que vous informiez votre acquéreur en amont.

Liste des éléments à fournir :

  • Nom commercial de la boutique ;
  • Numéro d'identification de la boutique :
    • VISA et Mastercard : Numéro de TVA intracommunautaire ;
    • CB : Token Requestor ID (fonctionnement temporaire initial) ;
    Note: Particularité du process initial CB : Vous devrez vous rapprocher de votre acquéreur afin de demander son enregistrement auprès du TSP CB. Une fois cet enregistrement réalisé, le GIE CB transmettra au marchand (via son acquéreur) un identifiant (Token Requestor ID) qui devra être commmuniqué à Worldline Sips.
  • URL de réception des notifications scheme token

Voici les cas d'utilisation du scheme token sur Worldline Sips lors de l'utilisation du merchant token .

Pour bénéficier de la scheme tokenisation sur les CIT, il est impératif d'avoir l'option merchant token d'activée.

La scheme tokenisation s'applique à partir d'une transaction remplissant les conditions suivantes :

  • Authentifiée (3-D Secure)
  • Autorisée
  • Merchant token renseigné
Note:

Aucune reprise de stock card-on-file n'est possible.

Le merchant token peut être renseigné :

  • par le commerçant
  • Suite à une transaction si l'option de le générer est activée

Voici le schéma de la scheme tokenisation avec un merchant token en entrée :


Schéma décrivant la génération d'un scheme token lors d'un paiement avec un merchant token

Le commerçant effectue un paiement avec un merchant token en appelant Worldline Sips. Si la transaction est bien authentifiée par 3-D Secure, la demande d'autorisation est effectuée avec les données carte associées au merchant token ainsi qu'avec les données d'authentification, et le commerçant reçoit la réponse à la demande d'autorisation avec le merchant token et les données d'authentification. Après la demande d'autorisation, Worldline Sips demande de façon asynchrone la création d'un scheme token au TSP, et stocke ce scheme token en l'associant au merchant token utilisé pour le paiement. Une fois le scheme token activé par le TSP, ce dernier notifie Worldline Sips, qui envoie à son tour une notification de mise à jour du scheme token au commerçant.

Voici le schéma de la scheme tokenisation sans merchant token en entrée mais avec l'option de génération sur une transaction activée :


Schéma décrivant la génération d'un scheme token lors d'un paiement avec des données carte

Le commerçant effectue un paiement avec des données carte en appelant Worldline Sips. Si la transaction est bien authentifiée par 3-D Secure, la demande d'autorisation est effectuée avec les données carte ainsi qu'avec les données d'authentification, un merchant token lié à cette carte est généré, et le commerçant reçoit la réponse à la demande d'autorisation avec le merchant token généré et les données d'authentification. Après la demande d'autorisation, Worldline Sips demande de façon asynchrone la création d'un scheme token au TSP, et stocke ce scheme token en l'associant au merchant token généré. Une fois le scheme token activé par le TSP, ce dernier notifie Worldline Sips, qui envoie à son tour une notification de mise à jour du scheme token au commerçant.

Comme décrit précédemment, la première transaction utilisant un merchant token n'utilisera pas le scheme token, et seule la génération de celui-ci sera effectuée.

La prochaine fois que ce merchant token sera utilisé, il sera remplacé par le scheme token qui lui est associé.

Voici un schema décrivant ce fonctionnement :


Schéma décrivant un paiement scheme token via le merchant token

Le commerçant appelle Worldline Sips avec un merchant token pour effectuer un paiement. Worldline Sips récupère le scheme token associé à ce merchant token, et utilise le scheme token au lieu des informations carte pour effectuer la demande d'autorisation, avant de répondre au commerçant avec le résultat de l'autorisation.

Si lors du processus une erreur survient avant la demande d'authorisation, Worldline Sips utilisera le PAN associé au merchant token et pas le scheme token.

Une fois créés, les scheme tokens suivent un cycle de vie, indiqué dans le schéma ci-dessous. Les changements de statut peuvent être déclenchés par les TSPs, comme par exemple dans le cas de l'expiration d'un scheme token.


schéma du cycle de vie d'un scheme token

Une fois créé, le scheme token a le statut "NOT_YET_ACTIVE". Après activation par le TSP, le scheme token passe au statut "ACTIVE". Depuis ce statut, le scheme token passe au statut définitif "DELETED" suite à l'action "DELETE", ou au statut "SUSPENDED" suite à l'action "SUSPEND". Un scheme token au statut "SUSPENDED" repasse au statut "ACTIVE" suite à l'action "ACTIVATE", ou passe au statut définitif "DELETED" suite à l'action "DELETE".

Le serveur Worldline Sips envoie une notification de mise à jour lorsque le statut d'un scheme token change, ou que les données carte associées à ce token sont mises à jour. Cette notification est une requête HTTP(S) POST au format similaire à celle de la réponse automatique Sips Paypage, sécurisée par le calcul d'une signature, le Seal.

La notification de mise à jour scheme token est directement envoyée à l'adresse URL de notification scheme token configurée dans votre contrat. Le serveur Worldline Sips n'attend aucune réponse après l'envoi de cette notification.

Il vous appartient de récupérer les différentes données de la notification, vérifier la signature pour vous assurer de l’intégrité des champs de la notification et, par conséquent, mettre à jour votre back office.

Attention:

La notification de mise à jour scheme token est systématique, asynchrone et renvoyée par le réseau. Elle est par définition dépendante des problèmes techniques potentiels des différents éléments de ce réseau et peut donc parfois être reçue avec un retard plus ou moins conséquent, voire ne jamais être reçue. La notification est envoyée en cas de mise à jour du scheme token. Toutefois, si aucune URL de notification n'est configurée dans votre contrat, le serveur Worldline Sips n'envoie pas de notification.

A l'instar de la réponse automatique Sips Paypage, la notification est composée des quatre données suivantes :

Données Notes/règles
Data Données de notification au format JSON.
Encode Type d'encodage utilisé pour la donnée Data. La notification de mise à jour scheme token n'étant pas encodée, cette valeur n'est pas renseignée.
Seal Signature de la notification.
InterfaceVersion Version de l'interface du connecteur. Le champ Data étant au format JSON, le format de la version est JS_3.x.

Si vous procédez à une authentification par sceau électronique (Seal), vous devez impérativement vérifier que le sceau reçu correspond bien au sceau que vous recalculez avec les champs de la notification.

Le sceau est calculé à l'aide de la clé secrète active la plus récente de votre contrat. La version de la clé secrète utilisée pour calculer la donnée Seal est indiquée par le champ keyVersion de la notification. Dans le cas d'un prestataire agissant pour le compte d'un commerçant, la clé secrète utilisée est celle de ce dernier, et l'identifiant du prestataire est spécifié dans le champ intermediateServiceProviderId. Cet identifiant correspond à celui qui a été fourni à l'inscription de l'option scheme token.

Si le sceau reçu ne correspond pas au sceau que vous recalculez, la notification reçue doit être considérée comme invalide.

La valeur de la donnée Seal est calculée comme suit :

  • utilisation de la clé secrète correspondant à la version spécifiée par le champ keyVersion pour générer la variante HMAC du message ;
  • utilisation de la donnée Data uniquement ;
  • codage UTF-8 des données constituant le résultat de l'opération précédente :
  • « Hashage » HMAC-SHA des octets obtenus.

Cette procédure peut être résumée comme suit :

HMAC-SHA256(UTF-8(Data), UTF-8(secretKey))

Pour le calcul de la donnée Seal, des exemples de code sont disponibles dans la documentation Sips Paypage.

IMPORTANT:

La donnée Seal de la notification de mise à jour scheme token est systématiquement calculée avec l'algorithme HMAC-SHA-256. Il est important de ne pas trier les données du champ Data pour calculer le Seal de la notification. Conservez les champs dans l'ordre dans lequel vous les avez reçus.

Les données de notification contenues dans le champ Data sont au format JSON, ayant la structure suivante : {"clé1":"valeur1","clé2":"valeur2",...}.

Exemple de données de notification :

{
	"keyVersion": 1,
	"merchantId": "029000254447216",
	"sealAlgorithm": "HMAC-SHA-256",
	"merchantToken": "AbcdEfghIjkLmNo/",
	"schemeTokenReference": "V:a123bc4d-5678-9efg-hi01-jk2l3mn456o7",
	"schemeTokenStatus": "ACTIVE",
	"schemeTokenExpiryDate": "203002",
	"schemeTokenSuffix": "0800",
	"schemeTokenRequestorId": "12345678901",
	"schemeTokenUpdateDateTime": "2025-04-01T12:12:35Z",
	"cardScheme": "VISA",
	"cardCobadgedScheme": "CB",
	"cardExpiryDate": "202601",
	"cardSuffix": "0400",
	"paymentAccountReference": "5577729c2fff49698bbce797637bc"
}

La liste ainsi que la description des champs de la notification de mise à jour scheme token sont disponibles sur cette page.

Parmi ces champs, ceux décrits dans le tableau ci-dessous permettent d'identifier le scheme token et de prendre connaissance de son état :

Champ Description
merchantToken Permet d'identifier le merchant token lié au scheme token mis à jour
schemeTokenReference Référence du Scheme Token, à utiliser pour identifier le token lors des appels à la méthode getCardMetadata du service Sips Office scheme token
schemeTokenStatus Indique le statut du scheme token

Les états possibles du scheme token retournés par la notification sont décrits dans le tableau ci-dessous :

État du scheme token Champ de la notification Description
En attente d'activation schemeTokenStatus = NOT_YET_ACTIVE Le scheme token est en attente d'activation par le TSP
Actif schemeTokenStatus = ACTIVE Le scheme token est actif et peut être utilisé à des fins de paiement
Suspendu schemeTokenStatus = SUSPENDED Le scheme token est suspendu et ne peut être utilisé à des fins de paiement, à moins qu'il ne soit réactivé
Supprimé schemeTokenStatus = DELETED Le scheme token est supprimé et ne peut plus être utilisé

Le cycle de vie d'un scheme token peut être suivi par un nouveau service Scheme Token via Sips Office.

Lorsque Worldline Sips vous envoie une notification relative à un changement associé au cycle de vie du scheme token, cette méthode vous permet de récupérer les informations liées au scheme token à l'aide de la référence de celui-ci.

Vous pourrez notamment récupérer des informations comme :
  • Le payment account reference
  • La date d'expiration de la carte
  • La date d'expiration du scheme token
  • Le suffixe de la carte (4 derniers chiffres)
  • Le statut du scheme token
Plus d'information disponible sur la page dédiée ici.

Si l'option est désactivée, les paiements ne seront plus faits avec un scheme token lié au merchant token. La cinématique de paiement sera comme avant son activation.

Ce site utilise des traceurs pour améliorer votre expérience de navigation, effectuer des analyses et des recherches sur votre utilisation du site web de documentation WL Sips.
En fermant ce bandeau vous refusez notre utilisation des traceurs sur votre appareil.

Paramètres