Cargos

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

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

Crear un cargo

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

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

GET /charges/:id/x402 → 402 Payment Required con los términos exactos (monto en USDC, dirección de tesorería, red).
Firma el pago y reintenta la misma petición con la cabecera X-PAYMENT.
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.

Objeto cargo

{
  "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.

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

Primeros pasos

Conceptos clave

Guías

Cargos

Cargos

Crear un cargo

Pagar un cargo

Desde la billetera de un agente

Vía x402 (USDC on-chain)

Objeto cargo

​Cargos

​Crear un cargo

​Pagar un cargo

​Desde la billetera de un agente

​Vía x402 (USDC on-chain)

​Objeto cargo

Cargos

Crear un cargo

Pagar un cargo

Desde la billetera de un agente

Vía x402 (USDC on-chain)

Objeto cargo