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

> Crea cargos, consulta su estado y deja que los agentes los paguen desde su billetera o on-chain vía x402.

# Cargos

## Crear un cargo

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

<ParamField body="amountUsdCents" type="integer" required>
  Monto en centavos de USD. `499` = \$4.99. Tiene que ser > 0.
</ParamField>

<ParamField body="description" type="string">
  Descripción legible por humanos (y por agentes). Aparece en el rastro de auditoría del agente.
</ParamField>

<ParamField body="externalId" type="string">
  Tu propio id (pedido, factura). Se te devuelve para conciliar.
</ParamField>

```json theme={null}
// 201 Created
{
  "chargeId": "chg_834e692669a3f8ad",
  "merchantId": "mch_c8fdac10d39c0c4d",
  "agentId": null,
  "amountMinor": 200,
  "currency": "USD",
  "description": "API credits pack",
  "externalId": null,
  "status": "pending",
  "method": null,
  "reference": null,
  "createdAt": "...",
  "paidAt": null
}
```

Dispara un webhook `charge.created`.

## Consultar un cargo

Público por `chargeId` (trata el id como la capacidad de acceso).

```bash theme={null}
GET /charges/chg_834e692669a3f8ad
```

Devuelve el [objeto cargo](/es/concepts/charges#objeto-cargo), o `404`.

## Pagar desde la billetera de un agente

```bash theme={null}
POST /charges/chg_xxx/pay
Authorization: Bearer pz_sk_...   # la key del agente que paga
```

### Éxito: pagado al instante

```json theme={null}
{
  "paid": true,
  "charge": { "status": "paid", "method": "ledger", "reference": "PAY_...", "...": "..." },
  "merchantBalanceMinor": 200
}
```

### Éxito: necesita aprobación humana

```json theme={null}
{
  "pendingApproval": true,
  "reason": "Monto $200 supera umbral de aprobación humana ($30 USDC)",
  "approvalId": "apr_f097d968cdb81c8d",
  "charge": { "status": "pending", "...": "..." }
}
```

No se cobró nada. Si se aprueba después (`POST /approvals/:id/grant` con autenticación de consola), recibes los webhooks `payment.succeeded` + `charge.succeeded`.

### Rechazado

```json theme={null}
{ "error": "Categoría 'services' no está en las categorías permitidas: ..." }
```

| Estado | Significado                                                                    |
| ------ | ------------------------------------------------------------------------------ |
| `402`  | Rechazado por política (límite, categoría o saldo). El cuerpo explica por qué. |
| `401`  | No es una key de agente válida.                                                |
| `409`  | El cargo no está en estado `pending`.                                          |

## Pagar on-chain (x402)

Para agentes sin billetera Payzor, el pago ocurre en USDC on-chain.

### Paso 1: pedir los términos

```bash theme={null}
GET /charges/chg_xxx/x402
```

Si está sin pagar, devuelve **`402 Payment Required`**:

```json theme={null}
{
  "x402Version": 1,
  "error": "Paga este cargo firmando USDC y reintentando con X-PAYMENT.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "10000",
      "resource": "https://host/charges/chg_xxx/x402",
      "payTo": "0xc80B...",
      "asset": "0x036Cb...",
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}
```

(Los cargos ya pagados devuelven el objeto cargo con `200` en su lugar.)

### Paso 2: reintentar firmado

Repite el mismo GET con la carga firmada en la cabecera:

```bash theme={null}
GET /charges/chg_xxx/x402
X-PAYMENT: <carga x402 codificada en base64url>
```

Payzor verifica y liquida contra el facilitador, marca el cargo como pagado (método `x402`, `reference` = hash de la transacción) y responde:

```json theme={null}
{
  "chargeId": "chg_xxx",
  "status": "paid",
  "settlement": { "success": true, "transaction": "0x..." }
}
```

Los fallos siguen siendo `402` con una explicación (`Pago inválido`, `Liquidación fallida`); el cliente puede corregir y reintentar.