Aller au contenu
Wajub

Bonnes pratiques

Les principes qui maintiennent une intégration fonctionnelle lorsque le parcours idéal n'est plus le seul possible.

Un démarrage rapide présente l'appel qui fonctionne. Ces cinq pages traitent des appels qui échouent : le délai dépassé qui vous empêche de savoir si un paiement existe, le webhook livré trois fois, la clé présente dans le bundle d'un navigateur ou l'exportation nocturne qui dépasse un plafond jamais mesuré.

Rien de tout cela n'est inhabituel. Chaque élément provient d'un échec que l'API peut réellement produire, et chaque page le décrit.

PageÉchec évitéCoût en cas d'absence
IdempotenceUne nouvelle tentative après un délai dépassé débite deux foisUn remboursement et la perte de confiance du client
Gestion des erreursTraiter un refus comme une panne, ou une panne comme un refusDes ventes perdues d'un côté, une tempête de nouvelles tentatives de l'autre
Bonnes pratiques de sécuritéUne clé secrète quitte votre serveurUn accès complet à l'API pour la personne qui la trouve
PerformancesParcourir une liste avec une requête par élémentDes exportations lentes qui consomment le quota nécessaire au checkout
Gestion des limites de requêtesUne tâche par lots entre en concurrence avec votre trafic liveUne erreur 429 sur l'appel attendu par un client

Moins coûteux avant la production qu'après

Chaque bonne pratique demande quelques lignes pendant l'intégration, mais entraîne une analyse d'incident si vous l'ajoutez plus tard. Intégrez-les à vos critères de fin de tâche.

Règle 1 : le navigateur ne confirme jamais un paiement

callback est une redirection. Le navigateur du payeur y arrive parce que la page hébergée l'y envoie. Aucun élément de cette URL n'est signé ni fiable. Un client peut l'ouvrir manuellement, l'ajouter à ses favoris ou y accéder après avoir fermé l'onglet pendant le paiement.

Les deux sources de vérité sont le webhook payment.succeeded et la requête GET /payments/{id} effectuée par votre serveur. Utilisez la page de retour pour afficher une information, jamais pour prendre une décision.

Règle 2 : vérifier la signature avant de lire le corps

Un endpoint de webhook qui analyse le corps avant la vérification peut être piloté par n'importe qui sur Internet. Vérifiez X-Wajub-Signature avec les octets bruts de la requête, puis analysez le corps.

# What Wajub sends you
POST /webhooks/wajub HTTP/1.1
X-Wajub-Signature: v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-Wajub-Timestamp: 1748083260
X-Wajub-Event: payment.succeeded
X-Wajub-Delivery-Id: whd_7Yh2MpL4tRb3nP8sZcXv
Content-Type: application/json

{"id":"evt_…","event":"payment.succeeded","data":{…}}

Le secret de signature provient du client que vous avez créé, pas d'un quatrième argument. Le transmettre ici remplace la fenêtre de tolérance et désactive silencieusement la protection contre les répétitions. Vérification de signature présente la méthode manuelle si vous n'utilisez aucun SDK.

Règle 3 : attribuer à chaque appel un identifiant facile à rechercher

Wajub ajoute X-Request-Id à chaque réponse et conserve la valeur que vous envoyez si elle ne dépasse pas 64 caractères. Envoyez votre propre identifiant de commande. La même chaîne identifiera l'appel dans vos logs, dans Konsole et dans tout ticket ouvert auprès du support.

Associer à un appel une valeur recherchable avec grep
curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "X-Request-Id: order-4172-attempt-1" \
  -H "Idempotency-Key: ORDER-4172" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "email": "buyer@example.com"
  }' -D -

-D - affiche les en-têtes de réponse. Vous voyez ainsi l'identifiant renvoyé avec X-Trace-Id et le champ W3C traceparent compris par les collecteurs OpenTelemetry.

Enregistrez peu d'informations de votre côté : l'identifiant de requête, l'uid du paiement, le statut HTTP et l'identifiant de chaque webhook accepté. Cela suffit pour répondre à la question importante lors d'un incident : une commande donnée a-t-elle atteint Wajub ?

Pages associées

Que pensez-vous de ce contenu ?