> ## 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

> Presupuestos preautorizados: un humano aprueba una vez, el comercio cobra muchas veces, y los límites duros siempre aplican.

# PayLinks

Un **PayLink** resuelve el problema del cobro recurrente para agentes.

Sin él, cada cargo mensual tendría que ser o bien lo bastante pequeño para autoaprobarse, o bien disparar una aprobación humana cada vez. Con un PayLink el humano aprueba **una sola vez** ("puedes gastar hasta \$5.00 con Acme este mes") y el comercio va cobrando contra ese presupuesto a medida que se consumen los servicios.

## Cómo funciona

<Steps>
  <Step title="El comercio crea el link">
    `POST /merchant/paylinks` con un presupuesto (por ejemplo 500 centavos = \$5.00), un tope opcional por cargo, un número máximo de usos y una caducidad. Devuelve un código corto tipo `h83YpjKQ`.
  </Step>

  <Step title="El agente lo acepta">
    El agente (actuando por su humano) revisa la vista pública y llama a `POST /pl/:code/accept`. Esto crea un **grant**, un registro auditable que dice que *un humano autorizó gastar hasta este presupuesto con este comercio*.
  </Step>

  <Step title="El comercio cobra contra el grant">
    `POST /merchant/paylinks/:code/charge` mueve dinero de la billetera del agente al saldo del comercio. No hace falta una nueva aprobación humana, pero tampoco se salta ningún límite duro.
  </Step>
</Steps>

## Cómo se hace cumplir el presupuesto

Cada cobro comprueba el presupuesto restante **antes** de tocar la billetera:

| Escenario           | Resultado                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| Cobro ≤ restante    | Pagado. La respuesta incluye `spentMinor`, `remainingMinor` y `exhausted`.                            |
| Cobro > restante    | Rechazado: `"error": "excede_presupuesto_restante_350"`; el mensaje te dice exactamente cuánto queda. |
| Presupuesto agotado | Rechazado: `"paylink_exhausted"`. Se dispara un webhook `budget.exhausted`.                           |

## Por qué esto es seguro

El grant registra *quién* aceptó y *cuándo*. Los cargos cobrados contra un grant quedan etiquetados con `method: paylink` en los rastros de auditoría de ambas partes. Si surge una disputa, puedes demostrar:

* el presupuesto exacto que autorizó el humano,
* cada cobro hecho contra él,
* y que nada lo excedió.

<Tip>
  Combina `perChargeUsdCents` con `maxUses` para armar planes medidos: por ejemplo presupuesto de $10, máximo $1 por cargo, 10 usos.
</Tip>

## Vista pública (sin autenticación)

`GET /pl/:code` devuelve todo lo que un agente necesita para decidir si acepta: nombre del negocio, etiqueta, presupuesto, restante y caducidad, sin exponer ningún dato sensible.