Suivre les statuts¶

Ce guide explique comment synchroniser les statuts de paiement avec votre PMS.

Stratégie de synchronisation¶

Deux approches complémentaires :

Méthode	Usage	Latence
Polling (GET statuses)	Synchronisation batch périodique	Quelques minutes
Webhooks (IPN)	Notification en temps réel	Quelques secondes

Synchronisation batch¶

L'endpoint /statuses/ est optimisé pour la synchronisation PMS. Il accepte une liste de références de réservations et retourne les statuts correspondants.

Requête¶

curl -H "X-API-Key: votre-clé-api" \
  "https://votre-domaine.com/api/payment-requests/statuses/?refs=RES-001,RES-002,RES-003"

Réponse¶

[
  {
    "uuid": "550e8400-...",
    "reference": "DEP-2026-0042",
    "reservation_ref": "RES-001",
    "request_type": "DEPOSIT",
    "status": "CAPTURED",
    "order_cycle": "CLOSED",
    "amount": 150.00,
    "amount_captured": 150.00
  },
  {
    "uuid": "7c9e6679-...",
    "reference": "IMP-2026-0015",
    "reservation_ref": "RES-002",
    "request_type": "IMPRINT",
    "status": "AUTHORISED",
    "order_cycle": "OPEN",
    "amount": 200.00,
    "amount_captured": 0.00
  }
]

Fréquence recommandée

Synchronisez toutes les 5 à 10 minutes pour un bon compromis entre fraîcheur des données et charge serveur.

Liste filtrée par statut¶

Pour récupérer toutes les demandes dans un statut donné :

# Toutes les demandes en attente
curl -H "X-API-Key: votre-clé-api" \
  "https://votre-domaine.com/api/payment-requests/?status=PENDING"

Statuts de référence¶

Statut	Code	Terminal	Description
Non initié	`NOT_INITIATED`	Non	Demande créée, formulaire non ouvert
En attente	`PENDING`	Non	Formulaire ouvert par le client
Autorisé	`AUTHORISED`	Non	Paiement autorisé (empreinte enregistrée)
A valider	`AUTHORISED_TO_VALIDATE`	Non	Pré-autorisation en attente de capture
Capturé	`CAPTURED`	Oui	Montant débité
Refusé	`REFUSED`	Oui	Refusé par la banque
Erreur	`ERROR`	Non	Erreur technique
Annulé	`CANCELLED`	Oui	Annulé par l'hôtel
Expiré	`EXPIRED`	Oui	Délai dépassé
Remboursé	`REFUNDED`	Oui	Montant remboursé

Champ order_cycle¶

Valeur	Signification
`OPEN`	Transaction en cours
`CLOSED`	Transaction terminée

Exemple d'intégration PMS¶

import requests

API_KEY = "votre-clé-api"
BASE_URL = "https://votre-domaine.com/api"

def sync_payment_statuses(reservation_refs: list[str]) -> dict:
    """Synchronise les statuts de paiement depuis M-Pay."""
    refs_param = ",".join(reservation_refs)
    response = requests.get(
        f"{BASE_URL}/payment-requests/statuses/",
        params={"refs": refs_param},
        headers={"X-API-Key": API_KEY},
    )
    response.raise_for_status()

    # Indexer par référence de réservation
    return {
        item["reservation_ref"]: item
        for item in response.json()
    }

# Usage
statuses = sync_payment_statuses(["RES-001", "RES-002", "RES-003"])

for ref, data in statuses.items():
    print(f"{ref}: {data['status']} ({data['amount_captured']}€ capturé)")