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

> Crea presupuestos preautorizados, publícalos para los agentes y cobra contra los grants aceptados.

# PayLinks

## Crear un PayLink

```bash theme={null}
POST /merchant/paylinks
Authorization: Bearer sk_mch_...
```

<ParamField body="label" type="string">
  Para qué es el presupuesto, por ejemplo `"Retainer mensual data"`. Se le muestra al agente antes de aceptar.
</ParamField>

<ParamField body="budgetUsdCents" type="integer" required>
  Techo total en centavos de USD sumando todos los cobros.
</ParamField>

<ParamField body="perChargeUsdCents" type="integer">
  Tamaño máximo de un cobro individual.
</ParamField>

<ParamField body="maxUses" type="integer">
  Número máximo de cobros.
</ParamField>

<ParamField body="expiresInHours" type="integer">
  Vida útil del link.
</ParamField>

```json theme={null}
// 201 Created
{
  "paylinkId": "pl_8eb56b59f563e9ed",
  "code": "h83YpjKQ",
  "business": null,
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "perChargeMinor": null,
  "maxUses": null,
  "uses": 0,
  "remainingMinor": 500,
  "expiresAt": null,
  "status": "active",
  "acceptUrl": "/pl/h83YpjKQ/accept"
}
```

## Vista pública

Todo lo que un agente necesita para decidir. No requiere autenticación.

```bash theme={null}
GET /pl/h83YpjKQ
```

```json theme={null}
{
  "paylinkId": "pl_...",
  "code": "h83YpjKQ",
  "business": "Acme Digital Goods",
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "perChargeMinor": null,
  "maxUses": null,
  "uses": 0,
  "remainingMinor": 500,
  "expiresAt": null,
  "status": "active"
}
```

## Aceptar un PayLink (agente)

Crea el grant, la autorización humana auditable. Es idempotente por par (link, agente).

```bash theme={null}
POST /pl/h83YpjKQ/accept
Authorization: Bearer pz_sk_...
```

```json theme={null}
{
  "grantId": "plg_8045a45414bdb863",
  "paylink": { "...": "vista pública..." }
}
```

Dispara `paylink.accepted` hacia los webhooks del comercio.

## Cobrar contra un grant

```bash theme={null}
POST /merchant/paylinks/:code/charge
Authorization: Bearer sk_mch_...
```

<ParamField body="agentId" type="string" required>
  De qué grant de agente se cobra. El agente tiene que haber aceptado antes.
</ParamField>

<ParamField body="amountUsdCents" type="integer" required>
  Monto del cobro en centavos de USD.
</ParamField>

<ParamField body="description" type="string">
  Qué paga este cobro.
</ParamField>

```json theme={null}
// 200 OK
{
  "paid": true,
  "charge": {
    "chargeId": "chg_610149bd78ab4857",
    "status": "paid",
    "method": "paylink",
    "reference": "PAY_82A95A672F30D580"
  },
  "spentMinor": 150,
  "remainingMinor": 350,
  "exhausted": false
}
```

### Catálogo de errores

| Estado | `error`                                    | Significado                                                                      |
| ------ | ------------------------------------------ | -------------------------------------------------------------------------------- |
| `402`  | `excede_presupuesto_restante_<N>`          | El cobro supera el presupuesto restante del agente (`N` = centavos que quedan).  |
| `402`  | `excede_tope_por_uso`                      | El cobro es mayor que `perChargeUsdCents`.                                       |
| `402`  | *(motivo de política)*                     | Los límites duros del agente lo bloquearon (tope diario, categoría...).          |
| `409`  | `paylink_exhausted`                        | Presupuesto consumido por completo. Ya se disparó un webhook `budget.exhausted`. |
| `409`  | `max_uses_alcanzado`                       | Se alcanzó el número máximo de cobros.                                           |
| `409`  | `paylink_expired` / `sin_grant_del_agente` | El link caducó, o este agente nunca lo aceptó.                                   |
| `404`  | `paylink_not_found`                        | Código equivocado, o el link pertenece a otro comercio.                          |

<Tip>
  El presupuesto restante se hace cumplir **antes** de tocar la billetera; un cobro rechazado nunca deja atrás un cargo a medias.
</Tip>