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.

Les SDKs serveur utilisent la clé secrète.

2. Enregistrer la clé

Python, Ruby, Go, Java et C# lisent automatiquement WAJUB_API_KEY dans l'environnement, et chaque SDK serveur se rabat sur 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

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.

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