Démarrage rapide des SDKs

Le parcours le plus court vers un paiement fonctionnel compte quatre étapes. Créez une clé dans le Dashboard, placez-la dans une variable d'environnement, installez un package et effectuez un appel. Vous recevez une URL qui ouvre une véritable page de paiement Wajub.

Tout le reste de cette section repose sur cet appel.

1. Obtenir une clé

Les clés se trouvent dans le Dashboard, sous Settings, puis Developer, puis API keys. Chaque compte possède deux jeux de clés dès le premier jour. Leur préfixe permet de les distinguer.

Une clé se compose d'un préfixe, d'un point, puis de 96 caractères. Les SDKs serveur utilisent la clé secrète.

2. Enregistrer la clé

Chaque SDK serveur lit automatiquement WAJUB_API_KEY et WAJUB_WEBHOOK_SECRET dans l'environnement. Un fichier .env suffit donc généralement pour toute la configuration.

WAJUB_API_KEY=sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…
WAJUB_WEBHOOK_SECRET=whsec_test_4f8c2b91d7e6a0f35c1dB7nY4hC6dF9j

Node.js constitue la seule exception. Il n'utilise pas de valeur de repli issue de l'environnement. Vous devez donc transmettre explicitement la clé, comme dans l'exemple ci-dessous.

3. Installer

Un package par langage, depuis le registre que vous utilisez déjà.

4. Créer un paiement

Voici l'appel : un montant, une devise, un moyen de contacter le client et une URL de retour.

curl https://api.wajub.com/payments \
  -H "Authorization: $WAJUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "XAF",
    "email": "amina@example.com",
    "description": "Order 4172",
    "reference": "order-4172",
    "callback": "https://shop.example.com/complete"
  }'

Seuls amount et currency sont réellement obligatoires. Vous devez aussi identifier le payeur avec l'un des trois champs email, phone ou customer_id. callback permet le fonctionnement du flux de redirection. reference est votre propre numéro de commande, renvoyé dans chaque webhook.

5. Lire la réponse

Les SDKs aplatissent l'enveloppe de l'API. Vous recevez donc un seul objet qui réunit les champs de la transaction et les deux champs d'autorisation.

Ouvrez maintenant authorization_url dans un navigateur. Cette page correspond au checkout et contient déjà l'image de marque de votre compte. La sandbox accepte les cartes et numéros de test.

6. Confirmer côté serveur

La redirection ramène le client vers votre URL de callback avec un paramètre status. Utilisez-le pour choisir la page à afficher, jamais pour livrer les biens.

curl https://api.wajub.com/payments/trx_test_8kQ2mW9vB4nL6hR1cY3d \
  -H "Authorization: $WAJUB_API_KEY"

Le navigateur n'est pas une source fiable. Un client peut fermer l'onglet après un paiement réussi. Une confirmation Mobile Money peut arriver plusieurs minutes après la redirection. La livraison du webhook est garantie. Livrez donc la commande à sa réception et utilisez cet appel comme repli.

Ce que le SDK fait pour vous

Les sept SDKs offrent le même comportement. C'est la raison d'utiliser un package plutôt qu'un appel HTTP brut.

En cas d'échec de l'appel

Chaque SDK génère une erreur typée au lieu de renvoyer un statut. La classe détermine l'action à prendre : réessayer, corriger la requête ou informer le payeur.

Deux écritures diffèrent de cette liste. PHP ajoute le suffixe Exception à ses sous-classes. La ligne ci-dessus devient donc InvalidRequestException, tandis que la base reste WajubError. Go écrit le sigle en majuscules, sa classe de connexion est donc APIConnectionError.

Quelle que soit la classe, quatre champs sont toujours présents : le message, un code, le statut HTTP et une map errors indexée par nom de champ. Affichez cette dernière dans votre formulaire.

import { WajubError, WajubInvalidRequestError, WajubRateLimitError } from '@wajub/node';

try {
  await wajub.payments.create({ amount, currency: 'XAF', email });
} catch (error) {
  if (error instanceof WajubInvalidRequestError) {
    return res.status(422).json({ fields: error.errors });
  }
  if (error instanceof WajubRateLimitError) {
    return res.status(503).set('Retry-After', String(error.retryAfter ?? 5)).end();
  }
  if (error instanceof WajubError) {
    logger.error({ code: error.code, status: error.httpStatus });
  }
  throw error;
}

Ruby, Java et C#

Tous trois fonctionnent exactement comme les cinq exemples ci-dessus, avec les mêmes dix-huit ressources et la même structure d'appel. Leurs pages adaptent chaque exemple à leurs conventions.

Étape suivante