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

# Cargos

> La unidad básica de cobro: un negocio dice 'este cliente me debe $X' y un agente lo liquida desde su billetera.

# Cargos

Un **cargo** es una intención de cobrar dinero. Nace como `pending` y pasa a `paid` cuando alguien lo liquida.

```text theme={null}
┌──────────┐   1. crear     ┌─────────────┐   2. pagar    ┌────────┐
│ Comercio │ ─────────────▶ │ Cargo       │ ◀──────────── │ Agente │
│ (sk_mch_)│                │ (pending)   │               │(pz_sk_)│
└──────────┘                └─────────────┘               └────────┘
                                   │  3. webhooks: charge.succeeded
                                   ▼
                            Saldo del comercio ↑
```

## Crear un cargo

```bash theme={null}
curl -X POST https://tu-host-payzor/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -d '{"amountUsdCents": 200, "description": "API credits pack", "externalId": "order_991"}'
```

* `amountUsdCents`: entero, siempre en centavos. `200` = **\$2.00**.
* `externalId`: tu propio id de pedido o factura, que se te devuelve para poder conciliar.
* Se dispara un webhook `charge.created` de inmediato.

## Pagar un cargo

### Desde la billetera de un agente

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

El pago pasa por el [Motor de Políticas](/es/concepts/policy-engine) de ese agente. Resultados posibles: pagado al instante, pendiente de aprobación humana o bloqueado. El cargo queda marcado con el id del agente que pagó, el método `ledger` y una referencia de pago.

### Vía x402 (USDC on-chain)

Cualquiera (incluso un agente sin billetera Payzor) puede liquidar on-chain:

1. `GET /charges/:id/x402` → `402 Payment Required` con los términos exactos (monto en USDC, dirección de tesorería, red).
2. Firma el pago y reintenta la misma petición con la cabecera `X-PAYMENT`.
3. Payzor verifica y liquida contra el facilitador, marca el cargo como pagado con método `x402` y devuelve el recibo de liquidación.

Ver [Pagos x402](/es/concepts/x402).

## Objeto cargo

```json theme={null}
{
  "chargeId": "chg_834e692669a3f8ad",
  "merchantId": "mch_c8fdac10d39c0c4d",
  "agentId": "agent_6b75c0e895ba9c3d",
  "amountMinor": 200,
  "currency": "USD",
  "description": "API credits pack",
  "status": "paid",
  "method": "ledger",
  "reference": "PAY_63FC9EDD0FAD129D",
  "createdAt": "2026-08-23T04:47:15.162Z",
  "paidAt": "2026-08-23T05:00:57.321Z"
}
```

| Campo       | Notas                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `status`    | `pending` → `paid`. Los estados de fallo y expiración están en la hoja de ruta; hoy los cargos siguen pendientes hasta que se pagan. |
| `method`    | Cómo se liquidó: `ledger` (billetera del agente), `paylink` (cobro contra presupuesto) o `x402` (on-chain).                          |
| `reference` | Referencia de pago para conciliación; coincide con el rastro de auditoría del agente.                                                |

<Note>
  Los cargos son idempotentes a nivel de estado: pagar un cargo ya pagado devuelve el cargo existente en vez de cobrar dos veces.
</Note>