Instant Payment Notification (Deprecated)

L’IPN est le mécanisme historique de notification d’Alma. Lorsqu’elle est activée, cette notification est envoyée de manière asynchrone environ 60 secondes après l’acceptation du paiement et le premier prélèvement.

Pour configurer une IPN, renseignez une URL :

  • dans la section Configuration d’API du dashboard Alma ;
  • ou dans le paramètre ipn_callback_url fourni lors de la création du paiement.

La notification prend la forme d’une requête HTTP GET vers l’URL configurée. Elle ne contient pas de corps et inclut l’identifiant du paiement dans le paramètre de requête pid :

GET https://example.com/alma/ipn?pid=<ID du paiement>

La requête contient également un en-tête X-Alma-Signature.

Contrairement aux nouveaux webhooks POST, l’IPN historique n’utilise pas de JWT. La valeur de X-Alma-Signature est une signature HMAC-SHA256 de l’identifiant du paiement, calculée avec votre clé API comme clé secrète et encodée au format hexadécimal :

HMAC-SHA256(
    clé = votre clé API,
    message = valeur du paramètre pid
)

Vérifier la signature de l’IPN

À la réception d’une IPN :

  1. Extrayez l’identifiant du paiement depuis le paramètre pid.
  2. Calculez le HMAC-SHA256 de cet identifiant en utilisant votre clé API comme clé secrète.
  3. Comparez le résultat calculé à la valeur de l’en-tête X-Alma-Signature.
  4. Effectuez cette comparaison en temps constant.
  5. Si les signatures ne correspondent pas, rejetez la requête et ne traitez pas la notification.

Exemple:

import hashlib
import hmac


def verify_alma_ipn(
    payment_id: str,
    signature_header: str,
    api_key: str,
) -> bool:
    expected_signature = hmac.new(
        key=api_key.encode("utf-8"),
        msg=payment_id.encode("utf-8"),
        digestmod=hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(
        expected_signature,
        signature_header,
    )

Une fois la signature validée, récupérez les données complètes du paiement via l’API Alma GET /v1/payment<ID>, avec votre clé API.

En cas d’erreur technique, répondez avec un code HTTP 4xx ou 5xx. Alma pourra alors renvoyer la notification.

Important : les nouveaux webhooks POST et les IPN historiques GET utilisent tous deux l’en-tête X-Alma-Signature, mais leur contenu est différent. Pour un webhook POST, il s’agit d’un JWT signé en RS256. Pour une IPN GET, il s’agit d’un HMAC-SHA256 hexadécimal de l’identifiant du paiement.