Aller au contenu

Premiers appels

Ce guide vous accompagne pour effectuer vos premiers appels API en 5 minutes.

1. Créer une demande de pré-paiement

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": "client@example.com",
    "guest_first_name": "Jean",
    "guest_last_name": "Dupont",
    "guest_phone": "+33612345678",
    "language": "fr",
    "reservation_ref": "RES-2026-042",
    "reservation_data": {
      "checkin": "2026-06-15",
      "checkout": "2026-06-18",
      "room": "Suite 201",
      "nights": 3
    }
  }' \
  https://votre-domaine.com/api/payment-requests/

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

Lien de paiement

Le payment_link est le chemin relatif vers le formulaire de paiement. Préparez l'URL complète : https://votre-domaine.com/payment/550e8400-...

2. Créer une empreinte bancaire

curl -X POST \
  -H "X-API-Key: votre-clé-api" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "IMPRINT",
    "amount": 200.00,
    "currency": "EUR",
    "guest_email": "client@example.com",
    "guest_first_name": "Marie",
    "guest_last_name": "Martin",
    "reservation_ref": "RES-2026-043",
    "language": "fr"
  }' \
  https://votre-domaine.com/api/payment-requests/

Réponse (201 Created) :

{
  "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reference": "IMP-2026-0015",
  "status": "NOT_INITIATED",
  "payment_link": "/payment/7c9e6679-7425-40de-944b-e07fc1f90ae7/"
}

Empreinte vs Pré-paiement

Pour une empreinte (IMPRINT), le montant représente le maximum capturable en cas de no-show. La carte du client n'est pas débitée lors de l'enregistrement.

3. Consulter l'état d'une demande

curl -H "X-API-Key: votre-clé-api" \
  https://votre-domaine.com/api/payment-requests/550e8400-e29b-41d4-a716-446655440000/

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": "client@example.com",
  "guest_first_name": "Jean",
  "guest_last_name": "Dupont",
  "reservation_ref": "RES-2026-042",
  "reservation_data": {
    "checkin": "2026-06-15",
    "checkout": "2026-06-18",
    "room": "Suite 201",
    "nights": 3
  },
  "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"
}

4. Synchroniser les statuts (batch)

Pour synchroniser plusieurs réservations d'un coup :

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

Réponse (200 OK) :

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

5. Annuler une demande

curl -X POST \
  -H "X-API-Key: votre-clé-api" \
  https://votre-domaine.com/api/payment-requests/550e8400-e29b-41d4-a716-446655440000/cancel/

Réponse (200 OK) :

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

Annulation

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

6. Capturer (no-show) ou libérer (client présent)

Pour les empreintes en statut AUTHORISED_TO_VALIDATE (pré-autorisation active) :

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

# Client présent : libérer la pré-autorisation
curl -X POST -H "X-API-Key: votre-clé-api" \
  https://votre-domaine.com/api/payment-requests/7c9e6679-.../release/

Pré-autorisation automatique

M-Pay crée automatiquement la pré-autorisation 2 jours avant le checkin si la date checkin est renseignée dans reservation_data. Voir le guide des scénarios pour le flux complet.

Étapes suivantes