Payment plans

Overview#

A payment plan splits an alternative's amount into a deposit, intermediate installments and a balance. It has a single payment URL: the traveler pays each installment there in turn, or the card they saved is charged automatically on each date.

In the API, a plan is a payment link of kind: "PLAN". On that link, amountCents is the installment payable now, never the total. The total and each installment are on the plan.

A plan opens on an alternative. Only one can be open at a time, and not next to an active reusable link. A plan has 2 to 7 payments: the deposit, then 1 to 6 payments, the balance included.

Create a plan#

Preview a plan#

Same body as creation. Nothing is written. The response gives the plan creation would make, and everything that would refuse it: valid is true when creation would succeed, short of a concurrent change. It is a POST, so it counts against the write limit.

{
  "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 mixes the schedule's codes and the alternative's state. sequence, when present, names the installment at fault (1 is the deposit).

warnings can hold INSTALLMENTS_TOO_CLOSE: accepted, but two payments are less than 14 days apart.

Create the plan#

Creates the plan and its link on an alternative of the booking. Returns 201 with the plan. The agency's Stripe account must be active (403 STRIPE_NOT_ACTIVE otherwise).

The schedule comes from one source:

• templateId: one of the agency's templates (see List templates). Its rules, collection mode and options apply to the booking.
• rules alone: the server computes the installments. The deposit is depositPercent % of the amount, rounded to the unit, due today. The balance is due balanceOffsetDays days before departure. Intermediate installments are spread between the two, and the balance absorbs the rounding.
• rules + installments: your own dates and amounts, revalidated with the same rules.

The body is strict: an unknown field returns 422 VALIDATION_ERROR instead of being ignored. templateId and rules together return 422 PLAN_SOURCE_AMBIGUOUS, neither of them 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"
    }
  }
}

Replay after a timeout#

There is no Idempotency-Key header, but creation is safe to replay: a second attempt on the same alternative returns 409 PAYMENT_PLAN_ALREADY_ACTIVE, with the id of the plan already open.

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

Read that plan with GET /v1/payment-plans/:id instead of creating another one.

Automatic debit#

With collectionMode: "AUTO_CHARGE", the traveler's card is charged on each date, after a notice. Only the traveler can turn it on: when paying the deposit on the plan's page, they click a button that names the authorization, for example "Pay €1,440.00 and activate the payment schedule". The API can neither give that consent nor save a card.

• The client's email is required, to notify them before each charge (422 AUTO_CHARGE_EMAIL_REQUIRED). For an Ezus booking, fix it in Ezus, then call POST /v1/bookings/:id/resync.
• Card only. allowedMethods must include card. SEPA is removed.
• After consent, autoCharge.active becomes true, with the card's brand and last 4 digits, and the payment_plan.auto_charge_activated webhook is sent.
• The traveler can decline by choosing "Pay the deposit only" ("Pay this installment only" after the deposit). The following installments then go to the link.
• Changing the amount or the date of an installment on a consented plan takes it off the debit: it will be paid by link, and the traveler is told. The other installments stay on the debit.
• A declined charge gets at most one retry three days later, announced to the traveler. An unusable card, or a bank asking the traveler to authenticate, moves the installment to the link.
• The traveler can turn the debit off from the plan's page, with "Turn off automatic payments". The agency can also cancel the plan.
• On a completed or cancelled plan, autoCharge.active is false. While the plan is paused, it stays true: the debit will resume.

Traveler emails#

Ezus Pay writes to the traveler, whoever created the plan: a notice before each charge, the link on the due date, a follow-up three days after an unpaid installment, declined charges, changed amounts or dates, cancellation. If your system also sends its own reminders, the traveler will get both.

In test mode, no email reaches the traveler. See Test mode.

Read plans#

List a booking's plans#

Every plan of the booking, across alternatives and statuses, newest first, in the shape above. Returns 404 BOOKING_NOT_FOUND for a booking outside your agency.

Retrieve a plan#

One plan, in the shape above. Returns 404 PAYMENT_PLAN_NOT_FOUND when the plan is not the key's agency's.

Plan links also show in GET /v1/bookings/:id/payment-links and GET /v1/payment-links/:id, with a plan summary. See the reference.

List templates#

The agency's plan templates, the default first. They are managed in Settings → Payment plans. The API does not change them.

{
  "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 (in the agency's currency) and suggestMinDaysBeforeDeparture are the template's suggestion conditions, null when there are none.

Retrieve the suggested plan#

The plan the agency's templates suggest on an alternative, computed on what is left to collect. The main alternative by default, or ?alternativeId= or ?ezusAlternativeId= for another one, never both. The template chosen is the most specific one whose conditions hold, otherwise the default template if its schedule is valid.

{
  "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 is null when no plan could be created or would help: a plan already open, an active reusable link, nothing left to collect, no departure date, a cancelled booking. matched is false when no template's conditions hold and the default template is offered. To create that plan, send its templateId.

Run a plan#

Each action returns the plan as it stands after it. A plan that moved between your read and your action (a payment just arrived) returns 409 PAYMENT_PLAN_CHANGED: read it again, then replay. While a payment of an installment is on its way, edits and cancellation return 409 INSTALLMENT_PROCESSING.

Edit installments#

Changes the dates and amounts of the unpaid installments. Send all of them, in order, by id. Their number does not change: to change it, cancel the plan and create another one. The total follows.

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

On a plan whose traveler consented to automatic debit, an installment whose amount or date changes goes to the link. See Automatic debit.

Pause and resume#

No notice, charge or automatic link goes out. The link stays payable, and the traveler is not told. No body.

Each installment whose date passed during the pause needs a new date, otherwise 422 RESUME_DECISIONS_REQUIRED. With no installment overdue, the body can be empty. The traveler receives the dates in force.

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

On a consented plan, a rescheduled installment goes to the link.

Cancel#

Cancels the unpaid installments and the link, detaches the card from the automatic debit and tells the traveler. What was paid stays paid: a refund goes through POST /v1/transactions/:id/refunds. No body.

Mark an installment paid#

For a payment received outside Stripe: a manual payment of the installment's exact amount is recorded, and the plan moves on. The next installment only (409 INSTALLMENT_NOT_NEXT otherwise). No fee, no email to the traveler.

Send the link again#

Sends the traveler the link of the next installment. Not twice within 10 minutes (429 LINK_RECENTLY_SENT). The response adds emailSent, which is false in test mode. The plan is abbreviated in the example below.

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

Test mode#

With an ezpay_test_ key, plans work as in production, automatic debit included, on the test Stripe account. No email reaches the traveler: each email is kept in the plan's journal.

Read the journal#

The plan's journal, oldest first. Available with a test key only (403 TEST_MODE_ONLY with a production key).

{
  "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 is APP (an agency member), API (a key) or SYSTEM (the charge scheduler, Stripe, the traveler).
• webhook is the event this entry sends to your endpoints, or null.
• email is the email that would have gone out in production, in the traveler's language.

Errors#

On top of the common errors:

To follow a plan without reading it again, subscribe your endpoints to the payment_plan.* and installment.* events. See Webhooks.