Authentification
Introduction
La sécurité est au cœur de nos préoccupations, c'est pourquoi nous avons pris des mesures pour vous aider à traiter les transactions de manière plus sûre. Pour réduire le risque que quelqu'un d'autre que vous puisse utiliser votre intégration, notre plateforme utilise des codes de sécurité liés à votre PSPID.
L'API Key et l'API Secret fournissent une signature unique au trafic entre votre système et notre plateforme. Vous pouvez les définir pour chacun de vos PSPID dans le Merchant Portal. Toute requête de serveur à serveur de votre système à notre plateforme (via votre PSPID) doit contenir à la fois l'API Key et l'API Secret. Notre plateforme essaie de faire correspondre les codes que nous recevons de votre part avec ceux configurés dans le Merchant Portal.
Nos SDK de serveur offrent une solution simple pour ce mécanisme, nécessitant seulement quelques lignes de code. Si vous souhaitez utiliser votre propre logiciel, une implémentation manuelle est également possible.
Ciblez l'URL de base de l'API la plus à jour
Nous vous encourageons à toujours cibler l'URL de base de l'API la plus à jour lors de l'envoi de requêtes à notre plateforme. Consultez notre guide dédié pour un aperçu complet.
Pour vous permettre une transition en douceur, les anciennes URL de base de l'API restent disponibles jusqu'à nouvel ordre.
Configuration de l'API Key/Secret
Configuration in the Back Office
Are you using the Back Office?
You can configure the API key/secret there as well. Learn here how to do it.
The API key/secret you configure in the Back Office can also be managed in the Merchant Portal (and vice versa), as they share the same data set.
Pour configurer la paire API Key / Secret dans le Merchant Portal, suivez ces étapes :
- Connectez-vous au Merchant Portal. Allez à Developer > Payment API
- Si vous n'avez encore rien configuré, l'écran affiche "No keys generated". Pour créer à la fois une paire API Key / Secret, cliquez sur “Add API Key”. L'écran affiche maintenant les deux codes dans le tableau respectivement sur les lignes “API Key ID” / “API Secret Key”.
Assurez-vous de sauvegarder l'API Secret dans votre système immédiatement après sa création, car il disparaîtra de cet écran après 60 secondes et ne sera plus jamais visible dans le Merchant Portal. Nous vous recommandons fortement de
- Conserver vos informations d'identification API dans un endroit sûr et sécurisé
- Ne les divulguer qu'aux parties, tel que votre développeur, qui nécessitent un accès pour créer et gérer vos intégrations
Vous pouvez consulter l'API Key et les informations suivantes concernant la paire API Key / Secret à tout moment via Developer > Payment API :
| Date d'expiration | Statut |
| La date à laquelle la paire API Key / Secret expirera (la durée de validité par défaut est de cinq ans) |
Le statut actuel de la paire API Key / Secret :
|
Si vous souhaitez utiliser une nouvelle paire API Key / Secret pour remplacer une paire existante, suivez ces étapes :
- Cliquez sur "Add API Key".
- Cliquez sur "Confirm" dans la boîte de dialogue pour procéder à la création d'une nouvelle paire API Key / Secret
Si vous avez déjà configuré une paire API Key / Secret dans votre PSPID, la création d'une nouvelle paire révoquera toujours celle existante. Une fois la nouvelle paire créée, l'ancienne paire expirera dans un délai de quatre heures. Pendant ce temps, assurez-vous de mettre à jour toutes les intégrations utilisant votre ancienne API Key/Secret avec la nouvelle paire générée. Cela évitera d'éventuelles interruptions dans votre activité commerciale.
- L'écran affiche maintenant la nouvelle paire API Key / Secret en bas du tableau avec le statut "Active". L'ancienne paire active est désormais en statut "Expiring in xh yym"
Assurez-vous de sauvegarder l'API Secret dans votre système immédiatement après sa création, car il disparaîtra de cet écran après 60 secondes et ne sera plus jamais visible dans le Merchant Portal. Nous vous recommandons fortement de :
- Conserver vos informations d'identification API dans un endroit sûr et sécurisé
- Les divulguer aux parties, tel que votre développeur, qui nécessitent un accès pour créer et gérer vos intégrations
Authentification avec le SDK
Une fois que vous avez configuré votre API Key/Secret dans le Merchant Portal, vous pouvez les utiliser pour les requêtes que vous envoyez à notre plateforme. Nos SDK Serveur facilitent grandement ce processus.
Jetez un œil à cet exemple de code qui montre comment les ajouter dans une demande standard de Hosted Checkout Page :
Ce mécanisme d'authentification est uniquement applicable à l'API serveur. L'API client utilise un mécanisme différent.
Authentification sans SDK
Vous pouvez utiliser notre API sans les SDKs en envoyant des requêtes directement à nos API endpoints. Cela nécessite de suivre un mécanisme d'authentification différent.
Essentiellement, vous devez :
- Hasher avec votre API Secret plusieurs en-têtes HTTP (les contenus de la signature ou données signées) que vous envoyez avec votre requête
- Envoyer ce hash (la signature) avec votre API Key pour vérifier l'authentification
Consultez les chapitres suivants pour comprendre comment cela fonctionne ainsi que nos exemples GET, POST et DELETE.
Comprendre le processus d'authentification
Une requête GET/POST/DELETE suivant cette approche inclut les étapes suivantes :
- Créer une chaîne-à-hasher, constituée de plusieurs en-têtes HTTP
- Calculer le hash en utilisant l'algorithme HMAC-SHA256 avec votre API Secret
- Envoyer la requête réelle à notre plateforme, en incluant les en-têtes, le hash et votre API Key
1. Créer une chaîne-à-hasher
Composez la chaîne-à-hasher (les contenus de la signature ou données signées) en suivant ces règles :
Ordre des en-têtes
La chaîne-à-hasher comprend les en-têtes suivantes, listées dans un ordre spécifique :
<HTTP Method>
<Content-Type>
<Date>
<CanonicalizedHeaders>
<CanonicalizedResource>
Conventions de contenu des en-têtes
Chaque en-tête est construit comme suit :
<nom d'en-tête en minuscule>:<valeur de l'en-tête>;
Appliquez les conventions suivantes pour le contenu des en-têtes :
| En-têtes | Conventions |
|---|---|
| <HTTP Method> | Utilisez "GET", "POST" ou "DELETE" (toujours en majuscules) selon la méthode HTTP utilisée. |
| <Content-Type> | Utilisez la valeur fixe "application/json; charset=utf-8" pour les requêtes POST et utilisez une chaîne vide pour les requêtes GET ou DELETE. |
| <Date> | Utilisez l'en-tête "Date" au format RFC1123. |
| <CanonicalizedHeaders> | Incluez des en-têtes personnalisées spécifiques à votre application, tel que X-GCS-ClientMetaInfo. |
| <CanonicalizedResource> | Incluez l'URI cible sans la méthode HTTP, et incluez tous les paramètres de requête décodés. |
Dérouler les valeurs des en-têtes
Si la valeur d'une en-tête est répartie sur plusieurs lignes, déroulez chaque ligne comme décrit ici. Déroulez en remplaçant une nouvelle ligne ou plusieurs espaces par un espace blanc unique.
Regardez cet exemple :
Une très longue ligne<CR><LF>
<SPACE><SPACE><SPACE><SPACE>qui ne tient pas sur une seule ligne
devient
Une très longue ligne qui ne tient pas sur une seule ligne
Supprimer les espaces blancs
Supprimez tous les espaces blancs qui existent au début et à la fin de la valeur.
Regardez cet exemple :
<espace><espace><espace>Un texte<espace><espace><espace>
devient
Un texte
Assurez-vous que chaque <item> est suivi d'une nouvelle ligne (retour à la ligne), y compris le dernier élément.
Jetez un œil à cet exemple de code pour une requête CreateHostedCheckout :
Bien que les mêmes règles s'appliquent pour chaque méthode HTTP, vous devez prendre en compte les différences pour les requêtes GET/DELETE lors de la création de la chaîne-à-hasher (c'est-à-dire l'absence de type de contenu, l'ajout de paramètres de requête à l'URI de la requête).
Consultez l'exemple GET ou l'exemple DELETE dans notre chapitre dédié pour savoir exactement ce que vous devez faire.
2. Calculer le hash
Une fois que vous avez créé la chaîne-à-hasher (les contenus de la signature ou données signées), vous devez la hasher via l'algorithme MAC HMAC-SHA256 avec votre API Secret.
Le résultat du hashage est la signature que vous devez fournir dans l'en-tête d'autorisation de votre requête.
Jetez un œil à cet exemple de code :
3. Envoyer la requête
Enfin, vous pouvez envoyer votre requête, en incluant :
- Les en-têtes que vous avez utilisées pour créer la chaîne-à-hasher (les contenus de la signature ou données signées)
- Le résultat du hash encodé en base64 (la “signature”) et votre API Key (que notre plateforme utilise pour identifier votre PSPID sur notre compte) dans l'en-tête HTTP 'Authorization' selon cette formule :
Authorization = "GCS v1HMAC:" + API Key + ":" + signature - Le corps de la requête encodé en JSON pour les requêtes POST (GET/DELETE ne nécessitent pas de corps de requête)
Jetez un œil à cet exemple de code :
Comprendre les exemples de chaîne-à-hasher
Comme les exigences générales pour une requête GET/POST/DELETE diffèrent, la construction de la chaîne-à-hasher diffère également.
Consultez les exemples suivants pour apprendre à les implémenter dans votre système :
1. Requête POST
La chaîne-à-hasher (les contenus de la signature ou données signées) pour une requête CreateHostedCheckout :
POST
application/json; charset=utf-8
Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/hostedcheckouts
Veuillez noter qu'il y a une nouvelle ligne (saut de ligne) après le dernier en-tête (ressource URI) que vous devez également prendre en compte lors du hachage de la chaîne.
2. Requête GET
La chaîne-à-hasher (les contenus de la signature ou données signées) pour une requête GetHostedCheckout :
GET
Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/hostedcheckouts/yourHostedCheckoutID
Notez que
- Il y a une chaîne vide pour l'en-tête Content-Type, car les requêtes GET n'ont pas de corps de requête
- Il y a une nouvelle ligne (retour à la ligne) après le dernier en-tête (ressource URI)
ce que vous devez également prendre en compte lors du hashage de la chaîne
3. Requête DELETE
La chaîne-à-hasher (les contenus de la signature ou données signées) pour une requête DeleteToken :
DELETE
Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/tokens/yourTokenID
Notez que
- Il y a une chaîne vide pour l'en-tête Content-Type, car les requêtes DELETE n'ont pas de corps de requête
- Il y a une nouvelle ligne (retour à la ligne) après le dernier en-tête (ressource URI)
ce que vous devez également prendre en compte lors du hashage de la chaîne