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

# Cobro recurrente con PayLinks

> Cóbrale a los agentes todo el mes sobre un presupuesto que aprobaron una sola vez. El modelo de suscripción de la economía de agentes.

# Cobro recurrente con PayLinks

Las tarjetas tienen el "guarda esta tarjeta y cóbrame cada mes". Los agentes tienen algo mejor: los **PayLinks** son presupuestos que un humano aprueba una vez y contra los que tú vas cobrando a medida que entregas valor.

## Cuándo usar un PayLink y cuándo cargos sueltos

| Usa cargos sueltos cuando...                            | Usa PayLinks cuando...                                          |
| ------------------------------------------------------- | --------------------------------------------------------------- |
| Son compras puntuales (un paquete de llamadas a la API) | Son servicios recurrentes (iguala mensual, planes por puesto)   |
| El monto es lo bastante pequeño como para autoaprobarse | Quieres una aprobación en vez de muchas                         |
| El agente te paga cuando le hace falta                  | Necesitas una exposición previsible y acotada para ambas partes |

## Recorrido completo

### 1. Crea el link

```bash theme={null}
curl -X POST https://tu-host-payzor/merchant/paylinks \
  -H "Authorization: Bearer sk_mch_..." \
  -d '{
    "label": "Retainer mensual data",
    "budgetUsdCents": 500,
    "perChargeUsdCents": 150,
    "maxUses": 10,
    "expiresInHours": 720
  }'
```

Todas las restricciones son opcionales salvo el presupuesto:

* `budgetUsdCents`: techo total sumando todos los cobros.
* `perChargeUsdCents`: tamaño máximo de un cobro individual.
* `maxUses`: número máximo de cobros.
* `expiresInHours`: se explica solo.

Respuesta:

```json theme={null}
{
  "paylinkId": "pl_8eb56b59f563e9ed",
  "code": "h83YpjKQ",
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "perChargeMinor": 150,
  "maxUses": 10,
  "remainingMinor": 500,
  "status": "active"
}
```

### 2. Hazle llegar el código al agente de tu cliente

El agente consulta la vista pública y decide:

```bash theme={null}
curl https://tu-host-payzor/pl/h83YpjKQ
```

```json theme={null}
{
  "code": "h83YpjKQ",
  "business": "Acme Digital Goods",
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "remainingMinor": 500,
  "status": "active"
}
```

Luego lo acepta (esto crea el grant, el "sí" auditable del lado humano):

```bash theme={null}
curl -X POST https://tu-host-payzor/pl/h83YpjKQ/accept \
  -H "Authorization: Bearer pz_sk_..."
```

```json theme={null}
{
  "grantId": "plg_8045a45414bdb863",
  "paylink": { "...": "..." }
}
```

Recibirás un webhook `paylink.accepted` con el id del grant y la identidad del agente.

### 3. Cobra cada vez que entregues valor

```bash theme={null}
curl -X POST https://tu-host-payzor/merchant/paylinks/h83YpjKQ/charge \
  -H "Authorization: Bearer sk_mch_..." \
  -d '{
    "agentId": "agent_6b75c0e895ba9c3d",
    "amountUsdCents": 150,
    "description": "Uso semanal"
  }'
```

```json theme={null}
{
  "paid": true,
  "charge": { "status": "paid", "method": "paylink", "...": "..." },
  "spentMinor": 150,
  "remainingMinor": 350,
  "exhausted": false
}
```

### 4. Maneja el agotamiento

Cuando el presupuesto restante llega a cero:

* los siguientes cobros devuelven `{ "error": "paylink_exhausted" }`,
* recibes un webhook final `budget.exhausted`,
* los cobros que exceden el presupuesto se rechazan *antes* de tocar la billetera, con el monto restante exacto en el mensaje de error.

## Patrones de diseño

<AccordionGroup>
  <Accordion title="Uso medido">
    Pon `perChargeUsdCents` a tu precio unitario y cobra una vez por periodo de facturación según el uso medido. El presupuesto acota el peor caso del cliente.
  </Accordion>

  <Accordion title="Planes por puesto">
    Un PayLink por cliente y por mes. Con `expiresInHours: 720` se retira solo; emites el link del mes siguiente en la renovación.
  </Accordion>

  <Accordion title="Pruebas gratuitas">
    Presupuesto pequeño (\$1), sin caducidad, suficiente para demostrar valor sin riesgo.
  </Accordion>
</AccordionGroup>