Payment window¶

A payment step can wait as long as its payment's account allows. A card checkout gives the payer minutes. A bank transfer can give days. A payment on arrival gives no deadline at all. The payment window deadline lets one step serve all three.

n_payment:
  id: n_payment
  label: Payment
  type: wait
  config:
    payload_variable: payment_outcome
    completion_scope: instance
  features:
    timeout:
      deadline: payment_window
      deadline_settings:
        duration: PT20M        # the fallback: time to start a payment
        anchor: node
      action: payment_lapsed
    interaction:
      plugin: kessai_payment
      settings:
        payable_resolver: my_resolver
        payment_timeout: P5D   # required: every payment ends within 5 days
        on_payment_expiry: retry  # the payer can try again until then

In the workflow editor, pick Payment window as the step's timeout deadline, and End the step if the payment has lapsed as its action. The editor refuses any other action: it would end the step when the fallback runs out, and cancel its payment, while the payer can still pay.

The editor also requires a payment timeout on the payment step. Without one, a payer who switches between payment options would start a payment with a fresh deadline each time, and the step would wait as long as they keep switching.

How long the step waits¶

Before the payer starts a payment, the step waits for the fallback duration. Its settings are those of the relative provider: a duration, what it is measured from, and how it counts (see Timers). When it runs out with no payment started, the step resumes with the expired outcome, as with any payment step.
The first payment starts the step's window. The window lasts the payment step's payment timeout, counted from when that first payment was created. Every payment of the step ends by the window's end, whatever account it goes through, so switching accounts or trying again never extends it.
While a payment is pending, the step waits for that payment's own deadline. Kessai stamps it from the payment's account, never later than the window's end: the provider's checkout session for a card, or the deadline a manual account sets.
When a payment fails or is canceled inside the window, the step does not end. It waits for the window's end, and the payer can start another payment until then, through any account still offered.
When a payment expires, the payment step's When a payment expires setting decides. End the step, the default, resumes the step with expired at once. Let the payer try again, until the step's own time is up treats the expiry like a failure: the step waits for the window's end, and the payer can start another payment until then.
At the window's end, with nothing paid, the step resumes with expired.

Set the payment timeout at least as long as the longest account's deadline, so that account keeps its full deadline on a first payment. See How long the payer gets.

For example, with a fallback of 20 minutes, a payment timeout of 5 days, the payer allowed to try again, a card account (20 minutes) and a bank transfer account (3 days):

When	What happens	The step
Minute 0	The booking reaches the payment step.	Waits 20 minutes for a first payment.
Minute 15	The payer starts a card payment. The window starts.	Waits for the card payment, until minute 35.
Minute 35	The card payment expires unpaid.	Keeps waiting, until the window's end, 5 days after minute 15.
Day 1	The payer starts a bank transfer.	Waits for the transfer, until day 4.
Day 4	The transfer expires: no money arrived.	Keeps waiting, until the window's end.
5 days after minute 15	Nothing was paid.	Resumes with `expired`.

Example: a bank transfer¶

The site has a manual payment account for bank transfers. Its payment deadline is 259200 seconds: three days. The step's fallback is 20 minutes, its payment timeout is 5 days, and it lets the payer try again when a payment expires.

The booking reaches the payment step. The step waits for 20 minutes.
The payer chooses to pay. Kessai creates the payment with a deadline three days ahead.
After 20 minutes, the step's timeout fires. The payment's window is still open, so the step keeps waiting. It now waits for the payment's deadline.
The transfer arrives. An operator records the payment as received, from the Kessai payments list. The step resumes with the paid outcome.
If nothing arrives in three days, Kessai expires the payment. The step keeps waiting: its window runs 5 days from the first payment, and the payer can still pay by card or start a new transfer, which gets the time left.
If nothing is paid within those 5 days, the step resumes with the expired outcome.

A payment on arrival account sets no deadline (0). Its payment then ends at the window's end, unless the operator records it before, when the guest arrives.

A step can offer the card and the bank transfer together, each payment with the deadline of its own account: see Letting the payer select an account.

When the timeout fires¶

The timeout fires when the fallback runs out, when a payment's deadline passes, when the window ends, or when an operator fires it early from the instance trace. The payment_lapsed action then looks at the step's pending payments:

The pending payment	What happens
None, before any payment	The step resumes with `expired`.
None, inside the step's window	The step keeps waiting, now for the window's end.
None, at the window's end	The step resumes with `expired`.
Its own deadline is still ahead	The step keeps waiting, now for the payment's deadline.
The payer is away at the provider	The step keeps waiting. Kessai asks the provider: paid, the payment resumes the step.
Its own deadline has passed	The payment is expired. With End the step, the step resumes with `expired`. Letting the payer try again, the step keeps waiting inside the window, and resumes with `expired` at its end.

A payment whose deadline has passed gives the step no new deadline. Kessai's sweep resolves it: paid, it resumes the step, and expired, it ends the step or leaves it waiting for the end of its window, as the setting says.

Holding the subject¶

The checkout's opening event carries the step's maximum deadline, the end of its window, so a subscriber can hold its subject until then (see Holding the subject still).

No event announces the payment as it is created. Kessai's kessai.initiated carries the payment, but a manual payment starts no provider session, so Kessai does not announce one for it.

The checkout's end is announced instead. Every outcome of one of the step's payments, kessai.captured, kessai.failed, kessai.expired, kessai.released and kessai.canceled, is marked handled: the workflow owns the payment, and one payment ending is not the checkout ending while the payer can still try again. When the step ends with nothing paid, however it ends, the checkout's closing event says so (see Holding the subject still). So a subscriber that holds its subject for days, like a booking whose places wait for a bank transfer, holds it from the opening event until the closing event or a payment that paid, rather than for a time it sets itself.

On another step¶

The payment window reads the payments the payment step pinned to its token. On a step that takes no payment, it only ever waits for the fallback duration, like the relative deadline.