Demandes de paiement¶

Référence complète des endpoints de l'API de gestion des demandes de paiement.

Créer une demande¶

POST /api/payment-requests/

Crée une nouvelle demande de paiement (pré-paiement ou empreinte bancaire).

Corps de la requête¶

Champ	Type	Requis	Défaut	Description
`request_type`	string	Oui	—	`IMPRINT` ou `DEPOSIT`
`amount`	decimal	DEPOSIT: oui	`0`	Montant en devise (ex: `150.00`)
`currency`	string	Non	`EUR`	Devise ISO 4217 (`EUR`, `CHF`, `USD`)
`guest_email`	string	Oui	—	Adresse email du client
`guest_first_name`	string	Oui	—	Prénom du client
`guest_last_name`	string	Oui	—	Nom du client
`guest_phone`	string	Non	`""`	Téléphone du client
`language`	string	Non	`fr`	Langue du formulaire : `fr`, `en`, `de`
`reservation_ref`	string	Oui	—	Référence de réservation dans votre PMS
`reservation_data`	object	Non	`{}`	Données supplémentaires (JSON libre)

Réponse `201 Created`¶

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "DEP-2026-0042",
  "status": "NOT_INITIATED",
  "payment_link": "/payment/550e8400-e29b-41d4-a716-446655440000/"
}

Erreurs¶

Code	Réponse	Cause
400	`{"error": "DEPOSIT requests require an amount greater than 0"}`	Pré-paiement sans montant
401	Non autorisé	Clé API manquante ou invalide

Exemple¶

curl -X POST \
  -H "X-API-Key: votre-clé-api" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "DEPOSIT",
    "amount": 150.00,
    "currency": "EUR",
    "guest_email": "jean.dupont@email.com",
    "guest_first_name": "Jean",
    "guest_last_name": "Dupont",
    "reservation_ref": "RES-2026-100"
  }' \
  https://votre-domaine.com/api/payment-requests/

Lister les demandes¶

GET /api/payment-requests/

Retourne la liste de toutes les demandes de paiement du tenant courant.

Paramètres de requête¶

Paramètre	Type	Description
`status`	string	Filtrer par statut (`PENDING`, `CAPTURED`, etc.)

Réponse `200 OK`¶

Tableau d'objets PaymentRequestDetail (voir Schémas).

Exemple¶

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

Détail d'une demande¶

GET /api/payment-requests/{uuid}/

Retourne le détail complet d'une demande de paiement.

Paramètres de chemin¶

Paramètre	Type	Description
`uuid`	string (UUID)	Identifiant unique de la demande

Réponse `200 OK`¶

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "DEP-2026-0042",
  "request_type": "DEPOSIT",
  "status": "CAPTURED",
  "amount": 150.00,
  "amount_captured": 150.00,
  "amount_refunded": 0.00,
  "currency": "EUR",
  "guest_email": "jean.dupont@email.com",
  "guest_first_name": "Jean",
  "guest_last_name": "Dupont",
  "reservation_ref": "RES-2026-100",
  "reservation_data": {
    "checkin": "2026-07-01",
    "checkout": "2026-07-05"
  },
  "masked_pan": "497010XXXXXX0014",
  "card_expiry_month": 12,
  "card_expiry_year": 2030,
  "order_cycle": "CLOSED",
  "email_sent": true,
  "created_at": "2026-03-08T10:30:00Z",
  "updated_at": "2026-03-08T10:35:00Z"
}

Erreurs¶

Code	Réponse	Cause
404	`{"error": "Payment request ... not found."}`	UUID inexistant

Synchroniser les statuts¶

GET /api/payment-requests/statuses/

Endpoint optimisé pour la synchronisation PMS. Par défaut retourne uniquement les demandes non acquittées ou modifiées depuis le dernier acquittement (changement de statut via webhook, capture, remboursement, etc.). Combiné avec POST /mark-retrieved/, il permet une sync incrémentale sans doublons.

Paramètres de requête¶

Paramètre	Type	Défaut	Description
`refs`	string	—	Références de réservation séparées par des virgules
`include_retrieved`	boolean	`false`	Si `true`, retourne tout (snapshot complet, ignore l'acquittement)

Réponse `200 OK`¶

[
  {
    "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
  }
]

Exemples¶

# Sync incrémentale (nouvelles + modifiées depuis dernier ack)
curl -H "X-API-Key: votre-clé-api" \
  "https://votre-domaine.com/api/payment-requests/statuses/"

# Snapshot complet pour audit / réconciliation
curl -H "X-API-Key: votre-clé-api" \
  "https://votre-domaine.com/api/payment-requests/statuses/?include_retrieved=true"

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

Fréquence recommandée

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

Flux recommandé

GET /statuses/ → récupère ce qui est nouveau ou a changé
Traite les demandes côté PMS (création d'arrhes, mise à jour du séjour, etc.)
POST /mark-retrieved/ avec les UUIDs traités pour les acquitter
Prochain GET /statuses/ ne renverra que ce qui a évolué entre-temps

Acquitter les demandes récupérées¶

POST /api/payment-requests/mark-retrieved/

Marque un lot de demandes comme « récupérées par le PMS ». Ces demandes ne réapparaîtront dans GET /statuses/ que si elles sont modifiées ultérieurement (ex. webhook de capture). Idempotent : ré-acquitter une demande déjà acquittée rafraîchit simplement son timestamp.

Corps de la requête¶

Champ	Type	Requis	Description
`uuids`	array of UUID	Oui	UUIDs des demandes à acquitter

{
  "uuids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ]
}

Réponse `200 OK`¶

{
  "marked": 2
}

marked est le nombre de lignes effectivement mises à jour (les UUIDs inconnus sont ignorés, pas d'erreur).

Erreurs¶

Code	Cause
401	Clé API manquante ou invalide
422	UUID mal formé dans `uuids`

Exemple¶

curl -X POST \
  -H "X-API-Key: votre-clé-api" \
  -H "Content-Type: application/json" \
  -d '{"uuids": ["550e8400-e29b-41d4-a716-446655440000"]}' \
  https://votre-domaine.com/api/payment-requests/mark-retrieved/

Batch plutôt qu'unitaire

Acquittez en une seule requête tous les UUIDs d'un même cycle de sync — c'est plus efficace qu'un appel par demande.

Capturer un paiement¶

POST /api/payment-requests/{uuid}/capture/

Capture (débite) un paiement pré-autorisé. Utilisé en cas de no-show pour les empreintes bancaires.

Paramètres de chemin¶

Paramètre	Type	Description
`uuid`	string (UUID)	Identifiant unique de la demande

Réponse `200 OK`¶

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "IMP-2026-0200",
  "status": "CAPTURED"
}

Erreurs¶

Code	Réponse	Cause
400	`{"error": "..."}`	Statut incompatible (doit être `AUTHORISED_TO_VALIDATE`)
404	`{"error": "Payment request ... not found."}`	UUID inexistant

Exemple¶

# No-show : capturer le montant garanti
curl -X POST -H "X-API-Key: votre-clé-api" \
  https://votre-domaine.com/api/payment-requests/550e8400-.../capture/

Pré-requis

La demande doit être en statut AUTHORISED_TO_VALIDATE (pré-autorisation active). Ce statut est atteint automatiquement J-2 avant le checkin pour les empreintes.

Libérer une pré-autorisation¶

POST /api/payment-requests/{uuid}/release/

Libère une pré-autorisation active. Le montant bloqué sur la carte du client est débloqué. Utilisé quand le client se présente.

Paramètres de chemin¶

Paramètre	Type	Description
`uuid`	string (UUID)	Identifiant unique de la demande

Réponse `200 OK`¶

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "IMP-2026-0200",
  "status": "CANCELLED"
}

Erreurs¶

Code	Réponse	Cause
400	`{"error": "..."}`	Statut incompatible (doit être `AUTHORISED_TO_VALIDATE`)
404	`{"error": "Payment request ... not found."}`	UUID inexistant

Exemple¶

# Le client est arrivé : libérer la garantie
curl -X POST -H "X-API-Key: votre-clé-api" \
  https://votre-domaine.com/api/payment-requests/550e8400-.../release/

Bonne pratique

Libérez toujours les pré-autorisations quand le client se présente. Sinon le montant reste bloqué sur sa carte jusqu'à expiration (jusqu'à 6 jours).

Annuler une demande¶

POST /api/payment-requests/{uuid}/cancel/

Annule une demande de paiement non finalisée.

Paramètres de chemin¶

Paramètre	Type	Description
`uuid`	string (UUID)	Identifiant unique de la demande

Réponse `200 OK`¶

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "DEP-2026-0042",
  "status": "CANCELLED"
}

Erreurs¶

Code	Réponse	Cause
400	`{"error": "..."}`	Demande déjà en statut terminal
404	`{"error": "Payment request ... not found."}`	UUID inexistant

Restriction

Seules les demandes non finalisées (NOT_INITIATED, PENDING, ERROR) peuvent être annulées. Un paiement déjà capturé ne peut pas être annulé — utilisez le remboursement via l'administration.

Supprimer une demande¶

DELETE /api/payment-requests/{uuid}/

Supprime définitivement une demande de paiement.

Paramètres de chemin¶

Paramètre	Type	Description
`uuid`	string (UUID)	Identifiant unique de la demande

Réponse `200 OK`¶

{
  "message": "Payment request DEP-2026-0042 deleted."
}

Erreurs¶

Code	Réponse	Cause
404	`{"error": "Payment request ... not found."}`	UUID inexistant

Action irréversible

La suppression est définitive. Préférez l'annulation pour conserver l'historique.

Demandes de paiement¶

Créer une demande¶

Corps de la requête¶

Réponse 201 Created¶

Erreurs¶

Exemple¶

Lister les demandes¶

Paramètres de requête¶

Réponse 200 OK¶

Exemple¶

Détail d'une demande¶

Paramètres de chemin¶

Réponse 200 OK¶

Erreurs¶

Synchroniser les statuts¶

Paramètres de requête¶

Réponse 200 OK¶

Exemples¶

Acquitter les demandes récupérées¶

Corps de la requête¶

Réponse 200 OK¶

Erreurs¶

Exemple¶

Capturer un paiement¶

Paramètres de chemin¶

Réponse 200 OK¶

Erreurs¶

Exemple¶

Libérer une pré-autorisation¶

Paramètres de chemin¶

Réponse 200 OK¶

Erreurs¶

Exemple¶

Annuler une demande¶

Paramètres de chemin¶

Réponse 200 OK¶

Erreurs¶

Supprimer une demande¶

Paramètres de chemin¶

Réponse 200 OK¶

Erreurs¶

Réponse `201 Created`¶

Réponse `200 OK`¶

Réponse `200 OK`¶

Réponse `200 OK`¶

Réponse `200 OK`¶

Réponse `200 OK`¶

Réponse `200 OK`¶

Réponse `200 OK`¶

Réponse `200 OK`¶