Plans de paiement

Vue d'ensemble#

Un plan de paiement répartit le montant d'une alternative en un acompte, des échéances intermédiaires et un solde. Il a une seule URL de paiement : le voyageur y règle chaque échéance à son tour, ou la carte qu'il a enregistrée est débitée automatiquement à chaque date.

Côté API, un plan est un lien de paiement de kind: "PLAN". Sur ce lien, amountCents vaut l'échéance à payer maintenant, jamais le total. Le total et chaque échéance se lisent sur le plan.

Un plan s'ouvre sur une alternative. Il ne peut y en avoir qu'un d'ouvert à la fois, et pas à côté d'un lien réutilisable actif. Un plan compte de 2 à 7 paiements : l'acompte, puis 1 à 6 paiements, dont le solde.

Créer un plan#

Calculer un aperçu#

Même corps que la création. Rien n'est écrit. La réponse dit le plan que la création ferait, et tout ce qui la refuserait : valid vaut true quand la création passerait, à un changement concurrent près. C'est un POST, il compte dans la limite des écritures.

{
  "success": true,
  "data": {
    "preview": {
      "alternative": { "id": "b3a1f0e2-6d4c-4e8a-9b7f-1c2d3e4f5a6b", "ezusAlternativeId": "ALT-1" },
      "template": { "id": "4d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d", "name": "Standard" },
      "amountCents": 480000,
      "currency": "EUR",
      "availableCents": 480000,
      "collectionMode": "AUTO_CHARGE",
      "rules": { "depositPercent": 30, "paymentsAfterDeposit": 2, "balanceOffsetDays": 45 },
      "installments": [
        { "amountCents": 144000, "dueDate": "2026-04-21" },
        { "amountCents": 168000, "dueDate": "2026-05-09" },
        { "amountCents": 168000, "dueDate": "2026-05-26" }
      ],
      "valid": true,
      "errors": [],
      "warnings": []
    }
  }
}

errors mêle les codes de l'échéancier et l'état de l'alternative. sequence, quand il est présent, désigne l'échéance en cause (1 est l'acompte).

warnings peut contenir INSTALLMENTS_TOO_CLOSE : accepté, mais deux paiements sont à moins de 14 jours d'écart.

Créer le plan#

Crée le plan et son lien sur une alternative du dossier. Renvoie 201 avec le plan. L'agence doit avoir un compte Stripe actif (403 STRIPE_NOT_ACTIVE sinon).

L'échéancier vient d'une seule source :

• templateId : un modèle de l'agence (voir Lister les modèles). Ses règles, son mode d'encaissement et ses options s'appliquent au dossier.
• rules seules : le serveur calcule les échéances. L'acompte vaut depositPercent % du montant, arrondi à l'unité, et tombe aujourd'hui. Le solde tombe balanceOffsetDays jours avant le départ. Les échéances intermédiaires se répartissent entre les deux, et le solde absorbe les arrondis.
• rules + installments : vos propres dates et montants, revalidés par les mêmes règles.

Le corps est strict : un champ inconnu renvoie 422 VALIDATION_ERROR au lieu d'être ignoré. templateId et rules ensemble renvoient 422 PLAN_SOURCE_AMBIGUOUS, aucun des deux 422 PLAN_SOURCE_REQUIRED.

curl -X POST https://api.ezuspay.app/v1/bookings/7c9e6679-7425-40de-944b-e07fc1f90ae7/payment-plans \
  -H "x-api-key: $EZP_KEY" -H "Content-Type: application/json" \
  -d '{
    "ezusAlternativeId": "ALT-1",
    "templateId": "4d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "collectionMode": "AUTO_CHARGE"
  }'

{
  "success": true,
  "data": {
    "paymentPlan": {
      "id": "9b2e4c1a-3f5d-4e6a-8b7c-0d1e2f3a4b5c",
      "status": "PENDING",
      "collectionMode": "AUTO_CHARGE",
      "totalAmountCents": 480000,
      "paidCents": 0,
      "installments": [
        { "id": "1a2b3c4d-0000-4000-8000-000000000001", "sequence": 1, "amountCents": 144000, "dueDate": "2026-04-21", "status": "SCHEDULED", "paidAt": null, "collectionMode": "AUTO_CHARGE" },
        { "id": "1a2b3c4d-0000-4000-8000-000000000002", "sequence": 2, "amountCents": 168000, "dueDate": "2026-05-09", "status": "SCHEDULED", "paidAt": null, "collectionMode": "AUTO_CHARGE" },
        { "id": "1a2b3c4d-0000-4000-8000-000000000003", "sequence": 3, "amountCents": 168000, "dueDate": "2026-05-26", "status": "SCHEDULED", "paidAt": null, "collectionMode": "AUTO_CHARGE" }
      ],
      "label": "2026-0042",
      "currency": "EUR",
      "allowedMethods": ["card"],
      "allowEarlyPayment": true,
      "remindersEnabled": true,
      "rules": { "name": "Standard", "depositPercent": 30, "paymentsAfterDeposit": 2, "balanceOffsetDays": 45 },
      "templateId": "4d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "attentionReason": null,
      "autoCharge": { "active": false, "cardBrand": null, "cardLast4": null },
      "createdVia": "API",
      "paymentLink": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "checkoutUrl": "https://app.ezuspay.io/lnk/voyages-horizon/8K3QZ7M2XR4T" },
      "booking": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "reference": "2026-0042", "ezusProjectId": "PRJ-1029" },
      "alternative": { "id": "b3a1f0e2-6d4c-4e8a-9b7f-1c2d3e4f5a6b", "ezusAlternativeId": "ALT-1" },
      "createdAt": "2026-04-21T09:15:00.000Z",
      "updatedAt": "2026-04-21T09:15:00.000Z"
    }
  }
}

Rejouer après un délai dépassé#

Il n'existe pas d'en-tête Idempotency-Key, mais la création est sûre à rejouer : une seconde tentative sur la même alternative renvoie 409 PAYMENT_PLAN_ALREADY_ACTIVE, avec l'identifiant du plan déjà ouvert.

{
  "success": false,
  "error": {
    "code": "PAYMENT_PLAN_ALREADY_ACTIVE",
    "message": "This alternative already has an open payment plan",
    "details": { "planId": "9b2e4c1a-3f5d-4e6a-8b7c-0d1e2f3a4b5c" }
  }
}

Lisez ce plan avec GET /v1/payment-plans/:id plutôt que d'en créer un autre.

Débit automatique#

Avec collectionMode: "AUTO_CHARGE", la carte du voyageur est débitée à chaque date, après un préavis. Seul le voyageur peut l'activer : en payant l'acompte sur la page du plan, il clique sur un bouton qui nomme l'autorisation, par exemple « Payer 1 440,00 € et activer l'échéancier ». L'API ne peut ni donner ce consentement ni enregistrer une carte.

• L'email du client est obligatoire, pour le prévenir avant chaque débit (422 AUTO_CHARGE_EMAIL_REQUIRED). Pour un dossier Ezus, corrigez-le dans Ezus puis appelez POST /v1/bookings/:id/resync.
• Carte uniquement. allowedMethods doit contenir card. Le SEPA est retiré d'office.
• Après le consentement, autoCharge.active passe à true, avec la marque et les 4 derniers chiffres de la carte, et le webhook payment_plan.auto_charge_activated part.
• Le voyageur peut refuser en choisissant « Payer uniquement l'acompte » (« Payer uniquement cette échéance » après l'acompte). Les échéances suivantes passent alors au lien.
• Modifier le montant ou la date d'une échéance d'un plan consenti la sort du débit : elle sera payée par lien, et le voyageur est prévenu. Les autres échéances restent débitées.
• Un débit refusé donne au plus un nouvel essai trois jours plus tard, annoncé au voyageur. Une carte inutilisable, ou une banque qui demande au voyageur de s'authentifier, fait passer l'échéance au lien.
• Le voyageur peut désactiver le débit depuis la page du plan, avec « Désactiver le débit automatique ». L'agence peut aussi annuler le plan.
• Sur un plan soldé ou annulé, autoCharge.active vaut false. Pendant une suspension, il reste true : le débit reprendra.

Emails au voyageur#

Ezus Pay écrit au voyageur, quel que soit l'auteur du plan : préavis avant chaque débit, lien le jour de l'échéance, relance trois jours après une échéance impayée, refus de débit, montant ou date changés, annulation. Si votre système envoie aussi ses propres relances, le voyageur recevra les deux.

En mode test, aucun email ne part au voyageur. Voir Mode test.

Lire les plans#

Lister les plans d'un dossier#

Tous les plans du dossier, toutes alternatives et tous statuts confondus, du plus récent au plus ancien, dans la forme ci-dessus. Renvoie 404 BOOKING_NOT_FOUND pour un dossier hors de votre agence.

Lire un plan#

Un plan, dans la forme ci-dessus. Renvoie 404 PAYMENT_PLAN_NOT_FOUND quand le plan n'est pas celui de l'agence de la clé.

Les liens de plan apparaissent aussi dans GET /v1/bookings/:id/payment-links et GET /v1/payment-links/:id, avec un résumé plan. Voir la référence.

Lister les modèles#

Les modèles de plan de l'agence, le modèle par défaut en tête. Ils se gèrent dans Paramètres → Plans de paiement. L'API ne les modifie pas.

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "4d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
        "name": "Standard",
        "isDefault": true,
        "depositPercent": 30,
        "paymentsAfterDeposit": 2,
        "balanceOffsetDays": 45,
        "collectionMode": "LINK",
        "remindersEnabled": true,
        "allowEarlyPayment": true,
        "suggestMinAmountCents": null,
        "suggestMinDaysBeforeDeparture": null
      }
    ]
  }
}

suggestMinAmountCents (dans la devise de l'agence) et suggestMinDaysBeforeDeparture sont les conditions de suggestion du modèle, null quand il n'y en a pas.

Lire le plan suggéré#

Le plan que les modèles de l'agence suggèrent sur une alternative, calculé sur ce qui reste à encaisser. L'alternative principale par défaut, ou ?alternativeId= ou ?ezusAlternativeId= pour une autre, jamais les deux. Le modèle retenu est le plus spécifique dont les conditions tiennent, sinon le modèle par défaut si son échéancier est valide.

{
  "success": true,
  "data": {
    "suggestion": {
      "template": { "id": "4d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d", "name": "Standard" },
      "alternative": { "id": "b3a1f0e2-6d4c-4e8a-9b7f-1c2d3e4f5a6b", "ezusAlternativeId": "ALT-1" },
      "amountCents": 480000,
      "currency": "EUR",
      "installments": [
        { "amountCents": 144000, "dueDate": "2026-04-21" },
        { "amountCents": 168000, "dueDate": "2026-05-09" },
        { "amountCents": 168000, "dueDate": "2026-05-26" }
      ],
      "matched": true
    }
  }
}

suggestion vaut null quand aucun plan ne peut être créé ou n'aiderait : plan déjà ouvert, lien réutilisable actif, rien à encaisser, pas de date de départ, dossier annulé. matched vaut false quand aucune condition de modèle ne tient et que le modèle par défaut est proposé. Pour créer ce plan, envoyez son templateId.

Faire vivre un plan#

Chaque action renvoie le plan tel qu'il est après elle. Un plan qui a bougé entre votre lecture et votre action (un paiement vient d'arriver) renvoie 409 PAYMENT_PLAN_CHANGED : relisez-le, puis rejouez. Tant qu'un paiement d'une échéance est en route, la modification et l'annulation renvoient 409 INSTALLMENT_PROCESSING.

Modifier les échéances#

Modifie les dates et les montants des échéances non payées. Envoyez-les toutes, dans l'ordre, par id. Leur nombre ne change pas : pour en changer, annulez le plan et créez-en un autre. Le total suit.

curl -X PATCH https://api.ezuspay.app/v1/payment-plans/9b2e4c1a-3f5d-4e6a-8b7c-0d1e2f3a4b5c \
  -H "x-api-key: $EZP_KEY" -H "Content-Type: application/json" \
  -d '{
    "installments": [
      { "id": "1a2b3c4d-0000-4000-8000-000000000002", "amountCents": 158000, "dueDate": "2026-05-12" },
      { "id": "1a2b3c4d-0000-4000-8000-000000000003", "amountCents": 178000, "dueDate": "2026-05-26" }
    ]
  }'

Sur un plan dont le voyageur a consenti au débit automatique, une échéance dont le montant ou la date change passe au lien. Voir Débit automatique.

Suspendre et reprendre#

Plus aucun préavis, débit ni lien automatique ne part. Le lien reste payable, et le voyageur n'est pas prévenu. Pas de corps.

Chaque échéance dont la date est passée pendant la suspension demande une nouvelle date, sinon 422 RESUME_DECISIONS_REQUIRED. Sans échéance dépassée, le corps peut être vide. Le voyageur reçoit les dates en vigueur.

{
  "decisions": [
    { "installmentId": "1a2b3c4d-0000-4000-8000-000000000002", "action": "reschedule", "dueDate": "2026-06-01" }
  ]
}

Sur un plan consenti, une échéance replanifiée passe au lien.

Annuler#

Annule les échéances non payées et le lien, détache la carte du débit automatique et prévient le voyageur. Ce qui est payé le reste : un remboursement passe par POST /v1/transactions/:id/refunds. Pas de corps.

Marquer une échéance réglée#

Pour un paiement reçu hors Stripe : un paiement manuel du montant exact de l'échéance est enregistré, et le plan avance. Seulement la prochaine échéance (409 INSTALLMENT_NOT_NEXT sinon). Pas de commission, pas d'email au voyageur.

Renvoyer le lien#

Envoie au voyageur le lien de la prochaine échéance. Pas deux fois en 10 minutes (429 LINK_RECENTLY_SENT). La réponse ajoute emailSent, qui vaut false en mode test. Dans l'exemple ci-dessous, le plan est abrégé.

{ "success": true, "data": { "paymentPlan": { "id": "9b2e4c1a-3f5d-4e6a-8b7c-0d1e2f3a4b5c" }, "emailSent": true } }

Mode test#

Avec une clé ezpay_test_, les plans fonctionnent comme en production, débit automatique compris, sur le compte Stripe de test. Aucun email ne part au voyageur : chaque email est gardé dans le journal du plan.

Lire le journal#

Le journal du plan, du plus ancien au plus récent. Disponible avec une clé de test uniquement (403 TEST_MODE_ONLY avec une clé de production).

{
  "success": true,
  "data": {
    "events": [
      { "id": "…", "kind": "CREATED", "occurredAt": "2026-04-21T09:15:00.000Z", "installmentId": null, "actor": "API", "webhook": "payment_plan.created", "email": null },
      {
        "id": "…",
        "kind": "NOTICE_SENT",
        "occurredAt": "2026-05-06T06:00:00.000Z",
        "installmentId": "1a2b3c4d-0000-4000-8000-000000000002",
        "actor": "SYSTEM",
        "webhook": null,
        "email": { "to": "jean@example.com", "subject": "Prélèvement de 1 680,00 € le 9 mai 2026 — Voyages Horizon", "text": "…" }
      }
    ]
  }
}

• actor vaut APP (un membre de l'agence), API (une clé) ou SYSTEM (le planificateur des débits, Stripe, le voyageur).
• webhook est l'événement que cette entrée envoie à vos endpoints, ou null.
• email est l'email qui serait parti en production, dans la langue du voyageur.

Erreurs#

En plus des erreurs communes :

Pour suivre un plan sans le relire, abonnez vos endpoints aux événements payment_plan.* et installment.*. Voir Webhooks.