Vérifier la signature des webhooks

La vérification de l'en-tête KartaPay-Signature est obligatoire avant d'agir sur le contenu d'un webhook.

1. Construire la chaîne du message

Concaténez ces champs, séparés par des virgules, dans cet ordre exact :

id,merchantId,clientId,value,currency,submittedAt,status

Champ	Exemple de valeur	Description
id	67928bcc4c9deaf5696a0942	L'identifiant du paiement
merchantId	f66d217e-22be-4e8c-a461-bcf9a355190a	Votre identifiant marchand KartaPay (contactez le support KartaPay)
clientId	de627e0d87fd2bdcdd7bf72b2c436379	L'identifiant de rapprochement entre votre système et KartaPay
value	1475	Valeur du paiement
currency	KMF	Devise du paiement
submittedAt	2025-01-23T18:34:58.846Z	Date de soumission du paiement
status	completed	Le statut du paiement

Exemple de chaîne de message :

67928bcc4c9deaf5696a0942,f66d217e-22be-4e8c-a461-bcf9a355190a,de627e0d87fd2bdcdd7bf72b2c436379,1475,KMF,2025-01-23T18:34:58.846Z,completed

Seuls ces 7 champs sont signés

La signature ne couvre que id, merchantId, clientId, value, currency, submittedAt et status. Les autres champs présents dans le contenu du webhook — topic, timestamp, type, captured, providerId, source (voir Recevoir des webhooks) — ne sont pas couverts par la signature. Ne basez aucune décision sensible en matière de sécurité sur ces champs non signés ; appuyez-vous sur le champ signé status, ou effectuez un appel API authentifié séparé pour confirmer l'état, si vous devez faire confiance à des informations non couvertes par la signature.

2. Calculer le HMAC-SHA256

Générez un HMAC-SHA256 de cette chaîne de message en utilisant le secret de webhook de votre tableau de bord.

danger

Conservez votre secret de webhook en sécurité dans votre système marchand — toute personne le possédant peut forger des webhooks d'apparence valide.

Python

import hmac
import hashlib

secret_key = b'secret_key'  # depuis votre tableau de bord KartaPay
message = b'67928bcc4c9deaf5696a0942,f66d217e-22be-4e8c-a461-bcf9a355190a,de627e0d87fd2bdcdd7bf72b2c436379,1475,KMF,2025-01-23T18:34:58.846Z,completed'

hmac_result = hmac.new(secret_key, message, hashlib.sha256).hexdigest()
print("HMAC-SHA256:", hmac_result)

Node.js

const crypto = require('crypto');

const secretKey = 'secret_key'; // depuis votre tableau de bord KartaPay
const message = '67928bcc4c9deaf5696a0942,f66d217e-22be-4e8c-a461-bcf9a355190a,de627e0d87fd2bdcdd7bf72b2c436379,1475,KMF,2025-01-23T18:34:58.846Z,completed';

const hmacResult = crypto
  .createHmac('sha256', secretKey)
  .update(message)
  .digest('hex');

console.log('HMAC-SHA256:', hmacResult);

3. Comparer les signatures

Comparez le HMAC que vous avez calculé à la valeur de l'en-tête KartaPay-Signature. Utilisez une comparaison à temps constant (par ex. hmac.compare_digest en Python ou crypto.timingSafeEqual en Node) pour éviter les attaques par mesure de temps. Ne faites confiance au contenu que si les valeurs correspondent exactement.

Étape suivante

Consultez Erreurs et idempotence pour gérer proprement les échecs de requête et les tentatives de nouvelle soumission.