​

Introduction

Cette section explique comment intégrer le mécanisme optionnel de signature de la charge utile (payload), qui garantit l’intégrité et l’authenticité de vos requêtes API. La signature est vérifiée uniquement sur les points de terminaison suivants :

• POST /payment-intents
• POST /payment-intents/:id/payments et POST /payment-intents/:id/payments/sync
• POST /transfers
• POST /irt/transfer et POST /irt/transfer/verified-recipient
• POST /terminal/payments
• POST /delegated/payments, POST /delegated/payments/sync, POST /delegated/transfers et POST /delegated/transfers/irt

Les autres points de terminaison, comme les remboursements, les dépôts, les liens de paiement et les sous-marchands, ne vérifient pas la signature.

​

Prérequis

Avant d’utiliser la signature de la charge utile, effectuez les étapes suivantes :

1. Générez une paire de clés RSA. La clé privée signe le corps de la requête ; la clé publique permet à HUB2 de vérifier la signature. Gardez la clé privée secrète.
2. Ajoutez la clé publique dans les préférences marchand du tableau de bord HUB2. Le tableau de bord accepte soit une clé publique RSA encodée en PEM (-----BEGIN PUBLIC KEY-----), soit un certificat X.509 encodé en PEM contenant cette clé (-----BEGIN CERTIFICATE-----). Deux clés peuvent être enregistrées, une actuelle et une précédente, afin de changer de clé sans interruption. Contactez l’équipe support si vous avez besoin d’aide pour cette étape.

​

Signer une requête

1. Sérialisez le corps JSON de la requête sous forme compacte (sans espaces ni retours à la ligne) et envoyez exactement cette chaîne comme corps.
2. Signez cette chaîne avec votre clé privée en RSA avec SHA-256 (RSA-SHA256, PKCS#1 v1.5).
3. Encodez la signature en Base64 et envoyez-la dans l’en-tête X-Signature.

HUB2 ne vérifie pas les octets bruts reçus : il analyse votre corps et recalcule la chaîne signée comme le fait JSON.stringify en JavaScript, avec le même ordre des clés, sans espaces, avec les caractères non ASCII et / non échappés, et les nombres sous leur forme la plus courte (1000, et non 1000.0). Un corps envoyé avec une indentation, des espaces superflus ou un autre échappement échoue donc à la vérification. Signez exactement cette chaîne, par exemple avec Python json.dumps(body, separators=(',', ':'), ensure_ascii=False) ou PHP json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES). En Python, passez les montants entiers en int (int(amount)) : json.dumps écrit un flottant comme 1000.0 avec son .0.

​

Environnement sandbox

Pendant le développement et les tests, avec l’en-tête Environment: sandbox :

• Si l’en-tête X-Signature est présent, HUB2 le vérifie avec les clés publiques enregistrées pour votre compte.
  • Si la signature est valide, la requête est traitée normalement.
  • Si la signature est invalide ou mal formée, l’API renvoie une erreur HTTP 400 avec le code signature_error.
• Si l’en-tête X-Signature est absent, la requête est traitée sans vérification de signature.

​

Environnement live

Pour imposer la vérification de la signature sur les transactions réelles (Environment: live), activez dans le tableau de bord HUB2 l’option qui force le trafic à utiliser la signature, en cochant la case correspondante. Une fois cette option activée :

• Toute requête avec Environment: live envoyée aux points de terminaison cités plus haut doit inclure un en-tête X-Signature valide.
• Si l’en-tête est absent ou si la signature est invalide, l’API renvoie une erreur HTTP 400 avec le code signature_error.

Tant que l’option est désactivée, les requêtes live ne sont pas vérifiées, même si elles incluent l’en-tête X-Signature. Conservez toujours votre clé privée en lieu sûr et mettez à jour les clés publiques dans le tableau de bord à chaque changement de paire de clés.