Vérifier les signatures des notifications

Ces API de commande (créer, interroger et renvoyer) utilisent les signatures HMAC-SHA256. GET /api/v1/ping nécessite uniquement une clé API. Les rappels de paiement incluent également une signature. HMAC utilise le secret de votre marchand Webhook, et non votre clé API.

01. Spécifications de l'en-tête

01. Envoi des requêtes de commande API

Client to Server

Les demandes de création, de requête et de renvoi nécessitent également X-Bolt-Key. Le timestamp doit être à moins de 5 minutes de l'horloge du serveur. Générez un nouveau timestamp et une nouvelle signature lors d'une nouvelle tentative.

Unix milliseconde timestampObligatoire

X-Bolt-Timestamp

Signature hexadécimale HMAC-SHA256Obligatoire

X-Bolt-Signature

02. Réception de rappels de paiement

Server to Merchant

BoltUtil génère des horodatages et des signatures de rappel. Les destinataires doivent vérifier le corps brut, vérifier la fenêtre timestamp et gérer les événements et les commandes commerciales de manière idempotente.

Unix milliseconde timestampObligatoire

X-Bolt-Webhook-Timestamp

Signature hexadécimale HMAC-SHA256Obligatoire

X-Bolt-Webhook-Signature

02. Calcul de signature

Construire le contenu signé

Concaténez l’horodatage de l’en-tête, un point et le corps original exact : timestamp + "." + raw_body. Utilisez UTF-8 et conservez le point même si le corps est vide.

// 1. Construct payload: timestamp + "." + body
String payload = timestamp + "." + body;

Calculer HMAC-SHA256

Utilisez le secret de la configuration Webhook de votre marchand. Le corps utilisé pour la signature doit correspondre exactement au corps envoyé dans votre demande API.

// JDK standard library: javax.crypto.Mac and SecretKeySpec
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));

Encoder en hexadécimal minuscule

Encodez le condensat de 32 octets en 64 caractères hexadécimaux minuscules. Envoyez-le dans X-Bolt-Signature pour les requêtes API. Vérifiez les notifications avec X-Bolt-Webhook-Signature par une comparaison en temps constant.

// JDK 17+: java.util.HexFormat
String signature = HexFormat.of().formatHex(hash);

03. Notes de vérification

Ne pas analyser et resérialiser JSON avant vérification. Les espaces, les sauts de ligne, l'ordre des touches et l'encodage affectent tous la signature.
HMAC vérifie l'intégrité du contenu mais n'empêche pas la relecture par lui-même. Vérifiez la fraîcheur du timestamp et dédoublonnez les événements.
Une signature valide ne signifie pas que l'exécution est terminée. Vérifiez l'association de la commande, le statut du paiement, les montants, la devise et le type de règlement.

Afficher la gestion des rappels →