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

# Aceptar un pago

> Integra Payzor en tu backend y empieza a aceptar pagos de agentes de IA, con el recorrido completo.

# Aceptar un pago

Esta es la guía de integración completa para negocios. Al terminar tendrás: cargos saliendo de tu backend, agentes pagándolos, webhooks confirmándolo todo y tu dinero en un saldo de comercio.

## Requisitos previos

* Una cuenta de consola en un despliegue de Payzor.
* Tu API key de comercio (`sk_mch_...`). Si no la tienes, mira el [paso 1 de la guía rápida](/es/quickstart#1-registra-tu-negocio).

## Arquitectura

Tu servidor nunca toca directamente las billeteras de los agentes. Tú creas **cargos**; Payzor mueve el dinero y te cuenta qué pasó vía **webhooks**.

```text theme={null}
Tu backend                  Payzor                      Agente del cliente
──────────                  ──────                      ──────────────────
POST /merchant/charges ───▶ cargo (pending)
                            ◀────────────────────────── POST /charges/:id/pay
                            política → debita billetera
◀── webhook: payment.succeeded / charge.succeeded
GET /merchant/me ─────────▶ saldo actualizado
```

## Paso a paso

### 1. Crea el cargo cuando toque facturar

Justo donde normalmente pedirías una tarjeta:

```bash theme={null}
curl -X POST https://tu-host-payzor/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsdCents": 499,
    "description": "Plan Pro - agosto",
    "externalId": "sub_42_invoice_8"
  }'
```

Guarda en tu base de datos el `chargeId` que te devuelve, asociado a tu `externalId`.

### 2. Dale al agente algo con qué pagar

El agente del cliente necesita saber *qué* pagar. Patrones habituales:

* **Tu API devuelve la URL de pago.** Incluye `"/charges/<id>/pay"` en la respuesta de tu API, allí donde un agente iría a mirar.
* **Tu documentación le dice a los desarrolladores de agentes** que conecten `POST /charges/:id/pay` en su bucle de herramientas.

El agente lo llama con su propia key; Payzor hace cumplir su política. Tú no haces nada más.

### 3. Maneja los resultados

| El agente recibe                        | Significado                    | Qué deberías hacer                                                  |
| --------------------------------------- | ------------------------------ | ------------------------------------------------------------------- |
| `{ paid: true, ... }`                   | Liquidado                      | Nada, el webhook lo confirmará.                                     |
| `{ pendingApproval: true, approvalId }` | Esperando al humano            | Espera; si se aprueba recibirás `payment.succeeded`.                |
| `{ error: "..." }`                      | Bloqueado por política o saldo | Deja que decida el agente (reintentar más tarde, bajar de plan...). |

### 4. Verifica que llegó

En desarrollo, consulta `GET /merchant/me`. En producción, apóyate en los webhooks ([guía](/es/guides/webhooks)).

## Conciliación

Cada cargo liquidado lleva:

* `chargeId`: tuyo para guardarlo,
* `reference`: coincide con la entrada en el rastro de auditoría del agente,
* `agentId`: quién pagó.

Para exportaciones contables, el usuario de consola puede descargar `GET /export/transactions.csv`; cada hecho con su número de secuencia y su hash de cadena.

## Checklist antes de salir a producción

<Checklist>
  <ChecklistItem>
    Endpoint de webhooks registrado y verificación de firma implementada.
  </ChecklistItem>

  <ChecklistItem>
    Dirección de payout configurada (`PUT /merchant/payout-address`); pasa el filtro KYT automáticamente.
  </ChecklistItem>

  <ChecklistItem>
    `externalId` guardado en cada cargo para que tus facturas concilien.
  </ChecklistItem>

  <ChecklistItem>
    Manejo idempotente de webhooks duplicados (pueden reintentarse).
  </ChecklistItem>
</Checklist>