Charges

Create a charge

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

integer

required

Amount in USD cents. 499 = $4.99. Must be > 0.

string

Human- (and agent-) readable description. Shows up in the agent’s audit trail.

string

Your own id (order, invoice). Echoed back for reconciliation.

// 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
}

Fires a charge.created webhook.

Get a charge

Public by chargeId (treat the id as the capability).

GET /charges/chg_834e692669a3f8ad

Returns the charge object, or 404.

Pay from an agent wallet

POST /charges/chg_xxx/pay
Authorization: Bearer pz_sk_...   # the paying agent's key

Success: paid instantly

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

Success: needs human approval

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

Nothing was charged. If approved later (POST /approvals/:id/grant with console auth), you receive payment.succeeded + charge.succeeded webhooks.

Rejected

{ "error": "Categoría 'services' no está en las categorías permitidas: ..." }

Status	Meaning
`402`	Policy rejected (limit/category/balance). Body explains why.
`401`	Not a valid agent key.
`409`	Charge not in `pending` state.

Pay on-chain (x402)

For agents without a Payzor wallet, payment happens in USDC on-chain.

Step 1: request terms

GET /charges/chg_xxx/x402

If unpaid, returns 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" }
    }
  ]
}

(Already-paid charges return the charge object with 200 instead.)

Step 2: retry signed

Repeat the same GET with the signed payload in the header:

GET /charges/chg_xxx/x402
X-PAYMENT: <base64url-encoded x402 payload>

Payzor verifies and settles against the facilitator, marks the charge paid (method x402, reference = tx hash) and responds:

{
  "chargeId": "chg_xxx",
  "status": "paid",
  "settlement": { "success": true, "transaction": "0x..." }
}

Failure modes are still 402s with an explanation (Pago inválido, Liquidación fallida); the client can fix and retry.

​Charges

​Create a charge

​Get a charge

​Pay from an agent wallet

​Success: paid instantly

​Success: needs human approval

​Rejected

​Pay on-chain (x402)

​Step 1: request terms

​Step 2: retry signed