Guía rápida

En esta guía vas a:

Crear una cuenta de comercio y obtener una API key.
Crear un cargo de $2.00.
Hacer que un agente lo pague desde su billetera Payzor.
Ver el dinero llegar a tu saldo de comercio.

Solo necesitas una API de Payzor en marcha (local o remota) y curl.

Antes de empezar, pídele al operador de Payzor (o a tu propia consola):

la URL base, por ejemplo http://localhost:3040

una sesión de consola para poder registrar tu negocio, y

una API key de agente (pz_sk_...) para simular el agente de tu cliente.

1. Registra tu negocio

El registro de comercios ocurre desde una sesión de consola con login. Entra por la interfaz de la consola (o tu flujo JWT existente) y llama a:

curl -X POST https://tu-host-payzor/merchants \
  -H "Authorization: Bearer <CONSOLE_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Digital Goods"}'

Respuesta: guarda la API key ahora, solo se muestra una vez:

{
  "merchantId": "mch_c8fdac10d39c0c4d",
  "apiKey": "sk_mch_3dc34f4326fa081f02b1e552a91b4696bb541572cbe89b23"
}

La key sk_mch_... se guarda hasheada. Si la pierdes, tienes que crear un comercio nuevo. Trátala como una contraseña.

2. Crea un cargo

Un cargo es una intención de cobro: “este cliente me debe $2.00”. Los montos son enteros en centavos de USD.

curl -X POST https://tu-host-payzor/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -H "Content-Type: application/json" \
  -d '{"amountUsdCents": 200, "description": "API credits pack"}'

Respuesta:

{
  "chargeId": "chg_834e692669a3f8ad",
  "merchantId": "mch_c8fdac10d39c0c4d",
  "amountMinor": 200,
  "currency": "USD",
  "description": "API credits pack",
  "status": "pending",
  ...
}

Guarda el chargeId: eso es lo que se paga.

3. Deja que el agente pague

El agente de tu cliente paga desde su billetera Payzor usando su key. La petición pasa automáticamente por el Motor de Políticas de ese agente:

curl -X POST https://tu-host-payzor/charges/chg_834e692669a3f8ad/pay \
  -H "Authorization: Bearer pz_sk_agent_key..."

Tres resultados posibles:

success

El dinero se movió al instante. Recibes de vuelta el cargo liquidado con su reference.

warning

El monto superó el umbral de aprobación humana del agente. Todavía no se ha cobrado nada; tiene que aprobarlo una persona. Tu webhook approval.required se dispara en ese mismo momento.

error

La política lo bloqueó (límite, categoría no permitida, saldo insuficiente). El agente no gastó nada.

4. Confirma que llegó el dinero

curl https://tu-host-payzor/merchant/me \
  -H "Authorization: Bearer sk_mch_..."

{
  "merchant": {
    "id": "mch_c8fdac10d39c0c4d",
    "name": "Acme Digital Goods",
    "balanceMinor": 200,
    "currency": "USD",
    "payoutAddress": null
  }
}

Eso es todo: un agente autónomo acaba de pagarte, dentro de unas reglas que definió un humano.

Qué pasó por debajo

Cada paso de arriba emitió eventos. Si hubieras registrado antes un endpoint de webhooks (un solo POST), habrías recibido charge.created, payment.succeeded y charge.succeeded, cada uno firmado con HMAC-SHA256. Ver Webhooks.

Por dónde seguir

Cobrar de forma recurrente

Usa PayLinks para preautorizar un presupuesto una vez y cobrar contra él todo el mes.

Referencia completa de la API

Todos los endpoints, parámetros y campos de respuesta.

Primeros pasos

Conceptos clave

Guías

Guía rápida

Guía rápida

1. Registra tu negocio

2. Crea un cargo

3. Deja que el agente pague

4. Confirma que llegó el dinero

Qué pasó por debajo

Por dónde seguir

Cobrar de forma recurrente

Referencia completa de la API

​Guía rápida

​1. Registra tu negocio

​2. Crea un cargo

​3. Deja que el agente pague

​4. Confirma que llegó el dinero

​Qué pasó por debajo

​Por dónde seguir

Cobrar de forma recurrente

Referencia completa de la API

Guía rápida

1. Registra tu negocio

2. Crea un cargo

3. Deja que el agente pague

4. Confirma que llegó el dinero

Qué pasó por debajo

Por dónde seguir