The three states
| Status | Meaning | What the caller hears |
|---|---|---|
required | Payment must complete before the call ends | ”Let’s knock out payment now so your order’s all set…” |
optional | Offer once, never block; unpaid is a valid outcome | One offer: “Want to take care of payment now?” |
not_required | No payment step at all for this business or purchase | Nothing. The call proceeds as the business’s normal flow |
The policy is per purchase, not per merchant
The same merchant can produce different statuses on different orders. A parts shop might make payment optional under $50 and required above it; only the amount changes the rule. That is why the payment step passesamount_cents when it asks, and why the answer cannot
be cached across calls.
not_required is the graceful floor
Unknown merchant, unconnected processor, a business that simply does not take phone
payments: all of these resolve to not_required, and the payment layer becomes inaudible.
This is a design guarantee, not an error path. It means the same agent configuration is
safe to run in front of every merchant on your platform, connected or not, from day one.
The
reason field is written for the model, not for display: it tells the payment step how
to behave in one sentence, so prompt and policy can never disagree.