Cargos

Crear un cargo

POST /merchant/charges
Authorization: Bearer sk_mch_...

integer

requerido

Monto en centavos de USD. 499 = $4.99. Tiene que ser > 0.

string

Descripción legible por humanos (y por agentes). Aparece en el rastro de auditoría del agente.

string

Tu propio id (pedido, factura). Se te devuelve para conciliar.

// 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).

GET /charges/chg_834e692669a3f8ad

Devuelve el objeto cargo, o 404.

Pagar desde la billetera de un agente

POST /charges/chg_xxx/pay
Authorization: Bearer pz_sk_...   # la key del agente que paga

Éxito: pagado al instante

{
  "paid": true,
  "charge": { "status": "paid", "method": "ledger", "reference": "PAY_...", "...": "..." },
  "merchantBalanceMinor": 200
}

Éxito: necesita aprobación humana

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

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

GET /charges/chg_xxx/x402

Si está sin pagar, devuelve 402 Payment Required:

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

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:

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

​Cargos

​Crear un cargo

​Consultar un cargo

​Pagar desde la billetera de un agente

​Éxito: pagado al instante

​Éxito: necesita aprobación humana

​Rechazado

​Pagar on-chain (x402)

​Paso 1: pedir los términos

​Paso 2: reintentar firmado