Legacy payments and guarded payments: what changes

This note explains how Zemtu handles reservation payments in the legacy flow and in the new guarded flow. It is not a change of payment provider. Stripe still handles card payments.

The change is inside Zemtu. The guarded flow checks whether a reservation is covered by money already captured plus a card authorization that Stripe can still use. The legacy flow continues to be used for payments that are still configured as legacy.

In this article, payment coverage means:

• captured money already held for the reservation

• plus any active card authorization that can still be used

Short comparison

Story 1: the first authorization failed, then the reservation changed

A driver books a vehicle and the first card authorization fails. Later, the reservation is updated.

With the guarded flow, the update can retry the authorization when the previous guarded record shows that the first authorization failed. If the retry succeeds, the payment gets a new recorded guarded action. If Stripe declines again, staff can see that the current attempt failed, not only that there was an older failed state.

This does not mean every declined payment is solved automatically. It means the current attempt and its result are visible.

Story 2: a reservation is prolonged

A customer books a vehicle for two hours, then extends it to ten hours.

The guarded flow recalculates the required coverage from the planned reservation duration and the active Stripe configuration. It counts money that is already captured and any active authorization that can still be used. If more coverage is required, it authorizes only the missing amount.

When an existing authorization has to be replaced, the guarded flow captures the current authorization and creates a new authorization for the remaining gap. If the captured amount already covers the current planned target, the guarded flow records that no provider action was needed.

Story 3: a long reservation approaches authorization expiry

Card authorizations are temporary. On long reservations, an authorization can expire before final capture.

The guarded flow can check guarded payments before authorization expiry. Before it changes anything, it confirms that the payment still needs action.

If the payment is still eligible, the guarded flow runs the same coverage logic used by the normal guarded path. If the amount needs approval, the payment is paused for that approval. If the authorization has already expired, the payment is marked for attention and the expired authorization is recorded.

Story 4: final settlement finds more captured money than needed

Sometimes the captured amount is higher than the final amount that should be charged.

During guarded final settlement, Zemtu can refund the overcaptured difference. The refund is based on the exact difference between captured coverage and the final target. If an unused authorization still exists, the guarded final settlement can cancel it as part of the same finalization path.

If the refund stays pending, Zemtu records the pending refund state. When the provider later confirms the refund, the guarded flow can continue final settlement without creating a duplicate refund.

Operator and support changes included in the same work

These items are less visible to drivers, but useful for operators and support teams:

• Support can inspect guarded payment history on the payment admin page when they have the required access.

• Payment history shows what the guarded flow did and why.

• Manual payment close first tries to release unused card holds.

• Authorization failure wording is more direct.

• The payment admin list can show recent payment activity.

What stays the same

Stripe remains the payment provider.

Legacy payments are not silently converted. Payments already on the legacy path continue to use the legacy path unless they are deliberately moved.

The guarded flow still avoids provider calls when the recorded coverage is already enough for the current guarded target.

Main benefit: future-proofing

The main benefit is not only the cases listed above. The guarded flow gives Zemtu a defined place to add payment rules deliberately: different behaviour for a customer, or additional handling for a case that should not stay on the old legacy path.

That matters because payment edge cases tend to be specific. One organization may want stricter handling for extensions. Another may want a different recovery path after a failed authorization. With the guarded payment toolbox, those decisions can be added to the guarded flow instead of being mixed into the older legacy process.

When the system acts, skips an action, or refuses to act, it records the reason. That gives operators and support a concrete payment story to inspect: what amount was required, what coverage existed, what action was taken, and why.