Configurer votre compte

Chaque appel à l'API Wajub est authentifié par une clé, et une clé appartient à un compte et à un environnement. Cette page vous emmène de l'absence de compte à un SDK qui s'authentifie, soit l'état dans lequel le démarrage rapide suppose que vous êtes déjà.

1. Créez votre compte

Inscrivez-vous sur dashboard.wajub.com avec votre nom, votre email et un mot de passe, puis confirmez l'email que nous vous envoyons. Rien n'est payant à ce stade : un nouveau compte démarre sur le plan gratuit Pay as you go.

Votre compte utilisateur vient d'abord, votre activité ensuite. Juste après la confirmation de votre email, le Dashboard vous demande de créer votre premier compte marchand, sur un écran intitulé Parlez-nous de votre activité :

Vous êtes le propriétaire de ce compte. Le Dashboard reste sur cet écran tant qu'il n'existe pas, et vous pourrez créer d'autres comptes marchands plus tard avec le même utilisateur.

Votre équipe est créée en sandbox, et elle y reste tant que la vérification de votre activité n'est pas approuvée. Rien de ce que vous faites maintenant ne peut déplacer de l'argent réel, et c'est tout l'intérêt : construisez et cassez librement avant que l'activation n'ouvre la production.

L'accueil du Dashboard affiche une checklist de configuration adaptée à ce que vous avez dit vouloir construire. Elle suit les mêmes étapes que cette page, vous pouvez donc suivre l'une ou l'autre.

2. Choisissez l'environnement avant de générer une clé

C'est l'étape que tout le monde saute. Une clé est générée pour l'environnement que le Dashboard affiche à ce moment-là. Basculez d'abord l'environnement sur Test ou sur Production, puis créez la clé. Créée dans le mauvais environnement, elle s'authentifiera sans problème tout en renvoyant les données d'un environnement auquel vous ne vouliez pas toucher.

Le live reste indisponible tant que votre compte n'est pas vérifié : d'ici là, chaque clé que vous créez est une clé _test, quoi que vous fassiez.

Changer d'environnement est en soi une permission. Le propriétaire du compte peut toujours le faire, les autres membres ont besoin d'un rôle qui le permet, Administrator ou Developer par défaut, et un membre au rôle Sandbox User ne peut jamais passer en live.

3. Créez votre première API key

Ouvrez Paramètres → Développeurs → Clés API et créez une clé. Vous choisissez le type, et le préfixe découle de ce choix et de l'environnement sélectionné à l'étape 2.

Commencez par une clé privée. Une clé restreinte vaut l'étape supplémentaire une fois que vous savez quels endpoints vous appelez réellement, et Environnements et API keys détaille les scopes, la liste d'IP autorisées et la date d'expiration que vous pouvez associer à chacune d'elles.

Si vous avez installé la CLI, wajub login le fait pour vous : la commande associe le terminal à votre compte via le navigateur, et le propriétaire, un Administrator ou un Developer (un Sandbox User aussi, pour une clé sandbox) approuve la demande et choisit l'environnement, Sandbox sauf s'il choisit Live. La CLI enregistre la clé dans un profil local. Cette clé expire au bout de 90 jours, et wajub login vous en donne une nouvelle. Connexion avec Wajub, dans le plugin WordPress, demande une clé de la même façon, et cette clé dure 90 jours sauf si la personne qui approuve choisit Durée indéterminée. Chaque clé créée par un appairage envoie un e-mail au propriétaire et à chaque Administrator.

4. Placez la clé dans votre environnement

Les clés vont dans l'environnement, jamais dans le code et jamais dans le dépôt. Créez un fichier .env à la racine de votre projet et gardez-le hors de git.

WAJUB_API_KEY=sk_test.xxxxxxxxxxxxxxxx…
WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx

WAJUB_API_KEY est le nom que tous les SDK reconnaissent : utilisez-le plutôt que d'inventer le vôtre. WAJUB_WEBHOOK_SECRET est le secret de signature d'un endpoint de webhook, un identifiant complètement différent, et c'est à l'étape 6 que vous en obtenez un.

5. Branchez la clé dans le SDK

Deux des SDK lisent WAJUB_API_KEY dans l'environnement d'eux-mêmes. Python et Go construisent un client fonctionnel à partir d'une configuration vide, c'est pourquoi les exemples ci-dessous ne passent rien.

Node et PHP ne lisent pas l'environnement et lèvent une erreur si la configuration est vide : vous leur passez donc la valeur vous-même.

import { Wajub } from '@wajub/node';

const wajub = new Wajub({ apiKey: process.env.WAJUB_API_KEY });

Quel que soit votre SDK, les quatre lisent WAJUB_WEBHOOK_SECRET d'eux-mêmes pour vérifier les signatures : une fois cette variable définie, vous ne passez jamais le secret explicitement.

6. Enregistrez un endpoint de webhook

Un paiement se confirme de façon asynchrone : votre serveur apprend donc le résultat par un webhook, et non par la réponse à l'appel qui l'a créé. Enregistrez l'endpoint maintenant, pendant que vous êtes dans le Dashboard, pour que le démarrage rapide ait une adresse où livrer.

Ouvrez Konsole → Webhooks → Points de terminaison, ajoutez votre URL et copiez le secret de signature affiché sur l'endpoint. Il ressemble à whsec_test_ suivi de 32 caractères en sandbox, et à whsec_ suivi de 32 caractères en production.

Ce secret est propre à chaque endpoint et à chaque environnement. Enregistrer à nouveau la même URL en live vous donne un secret différent : c'est pourquoi passer en production implique de copier un nouveau secret plutôt que de réutiliser celui que vous avez. Utilisez-le pour vérifier chaque signature entrante avant de faire confiance à un payload.

7. Renouvelez une clé qui a fuité

Le renouvellement remplace la valeur sur place. Le nom, les scopes et la liste d'IP autorisées sont conservés, l'ancienne valeur cesse de s'authentifier dès que vous confirmez, et il n'existe aucune période de grâce pendant laquelle les deux fonctionnent. Ayez donc la nouvelle valeur prête à déployer avant de cliquer, sinon vous subissez une interruption entre le renouvellement et la mise en production.

Comme cette action est destructive, le renouvellement demande un code de vérification de sécurité si vous n'en avez pas saisi un récemment. La suppression d'une clé demande la même chose.

8. Qui peut le faire dans votre équipe

Les API keys ne sont visibles que par le propriétaire du compte et par les membres qui ont la permission de gérer les API keys, que portent les rôles Administrator, Developer et Sandbox User. Les autres membres trouvent quand même Paramètres → Développeurs → Clés API dans le menu, mais la page répond « Vous n'avez pas la permission requise pour effectuer cette action. » : demandez à un admin de changer votre rôle. Équipe et sécurité liste ce que chaque rôle peut faire.

9. Quand la production s'ouvre

Les comptes vérifiés obtiennent leurs clés live de la même façon, en changeant d'environnement et en créant une clé. Les clés live sont des objets distincts : une clé sandbox n'est jamais promue. Prévoyez de remplacer ensemble la clé, l'URL du webhook et son nouveau secret de signature, et déroulez la checklist pour passer en live avant de le faire.