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. Retourne les statuts pour une liste de références de réservations.

Paramètres de requête¶

Paramètre	Type	Description
`refs`	string	Références de réservation séparées par des virgules

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
  }
]

Exemple¶

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

Fréquence recommandée

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

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¶

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`¶