Schémas¶

Référence des schémas de requête et réponse utilisés par l'API.

Schémas de requête¶

CreatePaymentRequest¶

Corps de la requête POST /api/payment-requests/.

{
  "request_type": "DEPOSIT",
  "amount": 150.00,
  "currency": "EUR",
  "guest_email": "client@example.com",
  "guest_first_name": "Jean",
  "guest_last_name": "Dupont",
  "guest_phone": "+33612345678",
  "language": "fr",
  "reservation_ref": "RES-2026-100",
  "reservation_data": {
    "checkin": "2026-07-01",
    "checkout": "2026-07-05"
  }
}

Champ	Type	Requis	Défaut	Description
`request_type`	`string`	Oui	—	Type de demande : `IMPRINT` ou `DEPOSIT`
`amount`	`number`	DEPOSIT: oui	`0`	Montant en devise
`currency`	`string`	Non	`"EUR"`	Code devise ISO 4217
`guest_email`	`string`	Oui	—	Email du client
`guest_first_name`	`string`	Oui	—	Prénom
`guest_last_name`	`string`	Oui	—	Nom
`guest_phone`	`string`	Non	`""`	Téléphone
`language`	`string`	Non	`"fr"`	Langue du formulaire
`reservation_ref`	`string`	Oui	—	Référence PMS
`reservation_data`	`object`	Non	`{}`	Données libres

Valeurs de `request_type`¶

Valeur	Description
`IMPRINT`	Empreinte bancaire — enregistre la carte sans débit
`DEPOSIT`	Pré-paiement — débite immédiatement le montant

Valeurs de `currency`¶

Code	Devise
`EUR`	Euro
`CHF`	Franc suisse
`USD`	Dollar américain

Valeurs de `language`¶

Code	Langue
`fr`	Français
`en`	Anglais
`de`	Allemand

Schémas de réponse¶

PaymentRequestResponse¶

Réponse à la création et à l'annulation.

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

Champ	Type	Description
`uuid`	`string` (UUID)	Identifiant unique
`reference`	`string`	Référence lisible (ex: `DEP-2026-0042`, `IMP-2026-0015`)
`status`	`string`	Statut courant
`payment_link`	`string`	Chemin relatif vers le formulaire de paiement

PaymentRequestDetail¶

Réponse au détail et à la liste.

{
  "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": "client@example.com",
  "guest_first_name": "Jean",
  "guest_last_name": "Dupont",
  "reservation_ref": "RES-2026-100",
  "reservation_data": {},
  "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"
}

Champ	Type	Description
`uuid`	`string` (UUID)	Identifiant unique
`reference`	`string`	Référence lisible
`request_type`	`string`	`IMPRINT` ou `DEPOSIT`
`status`	`string`	Statut courant (voir Statuts)
`amount`	`number`	Montant demandé
`amount_captured`	`number`	Montant effectivement débité
`amount_refunded`	`number`	Montant remboursé
`currency`	`string`	Code devise
`guest_email`	`string`	Email du client
`guest_first_name`	`string`	Prénom
`guest_last_name`	`string`	Nom
`reservation_ref`	`string`	Référence PMS
`reservation_data`	`object`	Données de réservation (JSON libre)
`masked_pan`	`string`	Numéro de carte masqué
`card_expiry_month`	`integer \\| null`	Mois d'expiration de la carte
`card_expiry_year`	`integer \\| null`	Année d'expiration de la carte
`order_cycle`	`string`	`OPEN` ou `CLOSED`
`email_sent`	`boolean`	Email de confirmation envoyé
`created_at`	`string` (ISO 8601)	Date de création
`updated_at`	`string` (ISO 8601)	Dernière mise à jour

PaymentRequestStatus¶

Réponse de l'endpoint de synchronisation batch.

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

Champ	Type	Description
`uuid`	`string` (UUID)	Identifiant unique
`reference`	`string`	Référence lisible
`reservation_ref`	`string`	Référence PMS
`request_type`	`string`	`IMPRINT` ou `DEPOSIT`
`status`	`string`	Statut courant
`order_cycle`	`string`	`OPEN` ou `CLOSED`
`amount`	`number`	Montant demandé
`amount_captured`	`number`	Montant débité

Error¶

Réponse d'erreur standard.

{
  "error": "Description de l'erreur"
}

Message¶

Réponse de confirmation (suppression).

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

Statuts¶

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

Order Cycle¶

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

Format des références¶

Les références sont générées automatiquement selon le type :

Type	Format	Exemple
`DEPOSIT`	`DEP-YYYY-NNNN`	`DEP-2026-0042`
`IMPRINT`	`IMP-YYYY-NNNN`	`IMP-2026-0015`