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

# El recorrido del dinero

> El viaje de ida y vuelta: cómo entra el dinero en Payzor, cómo se mueve cuando tu agente compra y cuando tu negocio vende, y dónde está físicamente en cada paso.

# El recorrido del dinero

Payzor tiene **dos lados**, y un mismo dólar puede recorrer los dos. Tu agente
**compra**: paga APIs, servicios y otros negocios. Tu negocio **vende**: le cobra
a los agentes que llegan. En medio, el dinero es una fila en un libro contable;
en los extremos, es USDC en una cadena.

Esta página es el viaje completo: por dónde entra, qué pasa en cada lado y dónde
acaba.

## El viaje de ida y vuelta

```mermaid theme={null}
flowchart TB
    subgraph IN["1 · El dinero entra"]
        W[Tu wallet externa<br/>MetaMask, Phantom, un exchange] -->|depositas USDC| CA[(Cuenta de cadena del agente<br/>custodiada por Payzor)]
        CA -->|el watcher lo acredita| LED[(Saldo del agente<br/>ledger de Payzor)]
    end

    subgraph BUY["2a · Lado compra — tu agente gasta"]
        LED --> POL{Motor de políticas}
        POL -->|dentro del perímetro| OK[Cargo pagado]
        POL -->|supera el umbral| HITL[Espera tu aprobación]
        HITL --> OK
    end

    subgraph SELL["2b · Lado venta — tu negocio cobra"]
        OK -->|transferencia interna<br/>no se mueve nada en cadena| MB[(Saldo del negocio)]
        X[Cualquier agente<br/>sin cuenta en Payzor] -->|pago x402 firmado| FAC[El facilitator liquida]
        FAC -->|el USDC aterriza on-chain| TRE[(Tesorería de Payzor)]
        FAC -->|acredita el libro| MB
    end

    subgraph OUT["3 · El dinero sale"]
        MB -->|retiro| DEST[Una dirección que tú controlas]
        LED -->|retiro del agente| DEST
        TRE -.->|los retiros salen de aquí| DEST
    end
```

<Note>
  Lee el diagrama como tres fases, no como cinco cajas: el dinero **entra** como
  USDC, **circula** como apuntes contables y **sale** otra vez como USDC. Los
  únicos pasos que tocan una blockchain son el depósito, un pago x402 y un retiro.
</Note>

## 1 · El dinero entra

Cada agente puede tener una cuenta de cadena, custodiada por Payzor a través de
Coinbase CDP.

```bash theme={null}
POST /agents/:id/chain      # crea la cuenta y devuelve la dirección de depósito
GET  /agents/:id/chain      # direcciones por red
```

Envía USDC a esa dirección desde cualquier wallet o exchange. Un watcher consulta
la cuenta y acredita el saldo del agente cuando el depósito llega. Para pruebas
también puedes acreditar el ledger directamente:

```bash theme={null}
POST /agents/:id/topup
```

<Tip>
  El **saldo del ledger** es lo que evalúa el motor de políticas y lo que paga
  los cargos. El **saldo en cadena** es el USDC que está en la dirección. Un
  depósito convierte el segundo en el primero.
</Tip>

## 2a · Lado compra — tu agente gasta

Tu agente paga desde su saldo del ledger. Cada pago pasa antes por el
[motor de políticas](/es/concepts/policy-engine): tope por transacción, tope
diario, categorías permitidas y umbral de aprobación humana.

* **Dentro del perímetro** → el cargo se paga al momento.
* **Por encima del umbral de aprobación** → no se debita nada. El pago espera a
  que tú lo apruebes y solo entonces se completa.
* **Fuera de un límite duro** → se bloquea, y queda registrado el motivo.

Pagar un cargo desde una wallet es una **transferencia interna**: el saldo del
agente baja, el del negocio sube, y no se mueve nada en ninguna cadena. Eso es lo
que hace viables los pagos de menos de un centavo: no hay gas que pagar.

## 2b · Lado venta — tu negocio cobra

Tu negocio publica algo que se pueda pagar: un [cargo](/es/concepts/charges), un
[link de pago](/es/api-reference/checkout), un producto del catálogo o un
[PayLink](/es/concepts/paylinks) con presupuesto pre-autorizado. A partir de ahí,
cualquier agente lo liquida de una de estas dos formas:

<CardGroup cols={2}>
  <Card title="Desde una wallet de Payzor" icon="wallet">
    El agente lleva una clave `pz_sk_`. El cargo se paga desde su saldo del
    ledger, bajo su propia política. Sin movimiento en cadena.
  </Card>

  <Card title="On-chain con x402" icon="link">
    El agente no tiene cuenta en Payzor. Responde al `402` con un pago firmado,
    el facilitator liquida en USDC y la venta se cierra en la misma petición.
  </Card>
</CardGroup>

En los dos casos sube tu **saldo de negocio** (`balance_minor`, siempre en
centavos de USD), la cadena de auditoría lo registra y se dispara un webhook
`charge.succeeded`.

## 3 · El dinero sale

Los dos lados pueden sacar el dinero a una dirección que controlen.

**Los retiros de negocio** siguen una máquina de estados explícita: un retiro
nunca es una sola llamada que se lanza y se olvida.

```mermaid theme={null}
flowchart LR
    R[solicitado] --> A[aprobado] --> S[enviando] --> D[enviado]
    R -.-> C[cancelado]
    A -.-> C
```

```bash theme={null}
POST /merchant/payouts              # solicitado  (screening KYT en este momento)
POST /merchant/payouts/:id/approve  # aprobado    (aquí se debita el saldo)
POST /merchant/payouts/:id/send     # enviando → enviado, on-chain
POST /merchant/payouts/:id/cancel   # cancelado, mientras siga solicitado o aprobado
GET  /merchant/payouts
```

La dirección de destino pasa screening KYT **en el momento del retiro**, no solo
cuando la guardaste. Cada solicitud lleva una clave de idempotencia, así que un
reintento no puede enviar los fondos dos veces.

**Los retiros de agente** funcionan igual desde el lado de la wallet:

```bash theme={null}
POST /agents/:id/withdrawals
POST /agents/:id/withdrawals/:wid/send
GET  /agents/:id/withdrawals
```

<Warning>
  Un retiro sale por la **misma red que la dirección de destino**, y cada cadena
  tiene su propio contrato de USDC. Enviar a una dirección de la cadena
  equivocada pierde los fondos y no tiene vuelta atrás: comprueba la red antes
  de aprobar. Consulta las [redes soportadas](/es/concepts/x402#redes-soportadas).
</Warning>

## Dónde está el dinero físicamente

La parte que es fácil perder de vista. Un saldo interno es un derecho de cobro
frente a Payzor; el USDC en sí está en un sitio concreto.

| Momento                                 | Saldo que ves              | Dónde está el USDC de verdad             |
| --------------------------------------- | -------------------------- | ---------------------------------------- |
| Después de un depósito                  | Saldo del agente           | En la cuenta de cadena del propio agente |
| El agente paga un cargo desde su wallet | Agente ↓ · Negocio ↑       | No se ha movido: es un apunte contable   |
| El agente paga con x402                 | Negocio ↑                  | En la tesorería de Payzor, on-chain      |
| Retiro solicitado                       | Saldo del negocio retenido | Sigue en la tesorería                    |
| Retiro enviado                          | Negocio ↓                  | En la dirección que tú controlas         |

<Note>
  Los retiros se financian desde la tesorería de Payzor, que es donde aterrizan
  las liquidaciones on-chain. Por eso un retiro es una transacción real con un
  hash que puedes consultar, mientras que pagar un cargo entre dos cuentas de
  Payzor no lo es.
</Note>

## Unidades, de una vez por todas

* La **API de comercio** habla en centavos de USD en todas partes:
  `amountUsdCents`, `amountMinor`, `balance_minor`. `2500` son **\$25.00**.
* El **motor de políticas** habla en dólares. La maquinaria de pago convierte
  antes de evaluar, así que un link de \$25.00 se compara con la política del
  agente como \$25.00, nunca como 2500.

<Tip>
  Cuando concilies, compara centavos con centavos. Mezclar las dos unidades por
  un factor de 100 es el error de integración más común que existe.
</Tip>