> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringup.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment policy

> Whether payment is required, optional, or absent is a merchant setting Ringup serves per purchase.

Every purchase gets exactly one policy decision, resolved server-side by Ringup at the
moment the payment step asks. Your agent never hard-codes it, and the merchant changes it
with no redeploy.

## The three states

```json theme={null}
{ "status": "required" | "optional" | "not_required", "reason": "..." }
```

| 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 passes `amount_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.

<Note>
  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.
</Note>