Sécurité de votre intégration

Protégez vos clés API

Votre clé sk_live_... donne un accès complet à votre compte. Elle n'a sa place que côté serveur, dans une variable d'environnement ou un gestionnaire de secrets, jamais dans une page web, une application mobile ou un dépôt de code.

# .env (jamais versionné)
ZAFEW_API_KEY=sk_live_...
ZAFEW_WEBHOOK_SECRET=whsec_...

Vérifiez la signature des webhooks

Chaque notification que nous vous envoyons porte l'en-tête X-Zafew-Signature : un HMAC-SHA256 du corps brut, calculé avec votre secret whsec_.... Recalculez-le de votre côté et comparez avant de traiter l'événement. Sinon, n'importe qui pourrait vous envoyer un faux « paiement reçu ».

import hashlib, hmac

def signature_valide(corps_brut: bytes, entete: str, secret: str) -> bool:
    attendu = hmac.new(secret.encode(), corps_brut, hashlib.sha256).hexdigest()
    # comparaison à temps constant contre les attaques temporelles
    return hmac.compare_digest(entete, attendu)

Utilisez toujours le corps brut (non re-sérialisé) et une comparaison à temps constant. Si vous régénérez votre secret, mettez à jour votre serveur avant, sinon les livraisons échoueront.

Restez en HTTPS

Toutes les requêtes vers zafew.com passent par HTTPS (TLS 1.2 ou plus). Les appels en HTTP clair sont refusés. Ne désactivez jamais la vérification du certificat SSL en production : c'est la porte ouverte à l'interception de vos jetons.

Validez ce que vous envoyez

Contrôlez les données avant chaque appel : un montant positif sous le plafond, un numéro MonCash au bon format, une référence de commande propre. Une validation en amont évite les erreurs coûteuses et les tentatives d'injection.

Évitez les doublons

Donnez à chaque commande un referenceId unique, et passez un en-tête Idempotency-Key sur pay-create. Si le réseau coupe et que vous rejouez la requête, c'est la même transaction qui revient : votre client n'est jamais débité deux fois.

Astuce : enregistrez la référence dans votre base avant l'appel. Vous pourrez retrouver le statut même si la réponse se perd.

Gérez les erreurs sans rien dévoiler

Journalisez le détail d'une erreur en interne, mais ne renvoyez au client qu'un message générique et la référence de commande. Une trace technique ou une clé qui fuit dans une réponse d'erreur, c'est un cadeau pour un attaquant.

try:
    traiter_paiement(donnees)
except Exception as e:
    log.error("echec paiement", extra={"reference": donnees["referenceId"]})
    # jamais de secret ni de trace dans la reponse au client
    return {"error": "paiement impossible", "reference": donnees["referenceId"]}

Testez d'abord, passez en réel ensuite

Faites tout votre développement en sandbox avec une clé sk_test_ : aucun argent réel, cycle de paiement complet, webhooks inclus. Ne basculez sur sk_live_ qu'une fois votre intégration validée, puis surveillez vos premières transactions de près.