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

# PayLinks

> Pre-authorized budgets: a human approves once, a merchant charges many times, hard limits always apply.

# PayLinks

A **PayLink** solves the recurring-billing problem for agents.

Without it, every monthly charge would either be tiny enough to auto-approve or trigger a human approval every time. With a PayLink, the human approves **once** ("you may spend up to \$5.00 with Acme this month") and the merchant draws against that budget as services are consumed.

## How it works

<Steps>
  <Step title="Merchant creates a link">
    `POST /merchant/paylinks` with a budget (e.g. 500 cents = \$5.00), an optional per-charge cap, max uses, and expiry. Gets back a short code like `h83YpjKQ`.
  </Step>

  <Step title="Agent accepts">
    The agent (acting for its human) inspects the public view and calls `POST /pl/:code/accept`. This creates a **grant**, an auditable record that says *a human authorized spending up to this budget with this merchant*.
  </Step>

  <Step title="Merchant charges against the grant">
    `POST /merchant/paylinks/:code/charge` pulls money from the agent's wallet into the merchant balance. No new human approval is needed, but no hard limit is bypassed either.
  </Step>
</Steps>

## Budget enforcement

Every draw checks the remaining budget **before** touching the wallet:

| Scenario          | Result                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| Draw ≤ remaining  | Paid. Response includes `spentMinor`, `remainingMinor`, `exhausted`.                               |
| Draw > remaining  | Rejected: `"error": "excede_presupuesto_restante_350"`; the message tells you exactly what's left. |
| Budget fully used | Rejected: `"paylink_exhausted"`. A `budget.exhausted` webhook fires.                               |

## Why this is safe

The grant records *who* accepted and *when*. Charges drawn against a grant are tagged `method: paylink` in both sides' audit trails. If a dispute arises, you can prove:

* the exact budget the human authorized,
* every draw made against it,
* and that nothing exceeded it.

<Tip>
  Combine `perChargeUsdCents` with `maxUses` to build metered plans: e.g. budget $10, max $1 per charge, 10 uses.
</Tip>

## Public view (no auth)

`GET /pl/:code` returns everything an agent needs to decide whether to accept: business name, label, budget, remaining, expiry, without exposing any sensitive data.