Démarrage rapide des SDKs

Obtenez une clé, installez un package et effectuez un appel : vous recevez une page de paiement Wajub à ouvrir, et un paiement que vous confirmez ensuite sur votre serveur.

1. Obtenir une clé

Les clés se trouvent dans le Dashboard, sous Paramètres, puis Développeurs, puis Clés API. Chaque compte possède deux jeux de clés dès le premier jour. Leur préfixe permet de les distinguer.

Les SDKs serveur utilisent la clé secrète.

2. Enregistrer la clé

Python, Ruby, Go, Java et C# lisent WAJUB_API_KEY dans l'environnement, et chaque SDK serveur lit WAJUB_WEBHOOK_SECRET. Un fichier .env suffit donc généralement pour toute la configuration.

WAJUB_API_KEY=sk_test.xxxxxxxxxxxxxxxx…
WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx

Node.js et PHP sont les exceptions pour la clé : ils ne lisent pas WAJUB_API_KEY. Vous devez donc transmettre explicitement la clé, comme dans les exemples 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

Vous recevez 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.

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.

Trois é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. Java ajoute Exception à toutes ses classes, la base comprise : WajubException, InvalidRequestException, ApiConnectionException, toutes non vérifiées. 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;
}

Étape suivante