Introduction
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.
À qui s’adresse ce document ?
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 :
Schéma de fonctionnement
Ce schéma décrit les relations techniques entre le marchand, Worldline Sips et les différents TSPs (Token Service Provider).
Inscription auprès des TSP
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
Cas d'utilisation
Voici les cas d'utilisation du scheme token sur Worldline Sips lors de l'utilisation du merchant token .
Scheme tokenisation lors d'une CIT avec 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é
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 :
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 :
Paiement avec le scheme token
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 :
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.
Suivre le cycle de vie du 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.
Recevoir la notification de mise à jour scheme token
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.
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. |
Vérifier la donnée Seal
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
keyVersionpour 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.
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.
Récupérer les champs de la notification
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é |
Méthodes du cycle de vie d'un scheme token
Le cycle de vie d'un scheme token peut être suivi par un nouveau service Scheme Token via Sips Office.
GetCardMetaData
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.
- 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
Désactivation de l'option scheme token
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.
